Quds DB Interface

A highly modular, engine-agnostic database abstraction layer for Dart and Flutter applications.

quds_db_interface provides the foundational blueprint for building pure-Dart architectures. It defines strongly-typed properties, strict query-builders, and automated table providers without tightly coupling your application to any specific database engine (such as SQLite, MySQL, or PostgreSQL).

Core Architecture

The architecture is divided into four core pillars, designed to provide maximum type safety and minimal boilerplate.

1. DbModel: Represents a database table row. Models are defined by pure-Dart FieldDefinition properties (StringField, IntField, BoolField, JsonField, etc.), ensuring strict typing across the entire database layer.
2. TableProvider: The engine responsible for all CRUD operations and bulk transactions. It accepts strict closures (Condition Function(T model)) to guarantee compile-time type safety over database reads, writes, and filtering logic.
3. QueryBuilder: Provides complex, multi-table relationship capabilities (such as INNER JOIN and LEFT JOIN) and aggregations (GROUP BY, HAVING, MAX, COUNT).
4. DatabaseAdapter & DatabaseConnection: The lowest-level wrapper that manages execution and handles transactions natively via a zone-based execution context (transaction(() async { ... })).
5. Migrations: Versioned, Dart-first schema evolution through connection.migrations (Migration, MigrationContext, SchemaMigrationRunner). Prefer typed helpers such as createTable / addColumn / updateRows; use rawSql only when an engine-specific edge case cannot be expressed in Dart.

Key Concepts and Recent Updates

Silent Bulk Operations

The interface inherently supports optimized bulk processing. Methods like insertCollection are designed to suppress individual entry listeners during bulk operations. Instead of triggering a UI rebuild for every inserted row, implementing packages notify listeners exactly once via EntryChangeType.collectionInsertion when the bulk transaction has been safely and atomically committed.

Zone-Based Transactions

The interface standardizes the concept of Zone-based transactions. By wrapping logic in connection.transaction(), implementers can provide a seamless transaction context to all underlying providers, removing the need to manually pass a transaction object throughout the application architecture.

Building an Implementer

If you intend to implement this interface for a specific engine (e.g., PostgreSQL or SQLite), you must satisfy the following components:

1. Adapter implementation: Implement DatabaseAdapter to handle database initialization, connection pooling, and configuration settings.
2. Connection implementation: Implement DatabaseConnection to route rawQuery, rawExecute, and transaction blocks to the native engine SDK.
3. Provider implementation: Extend TableProvider<T> or StandardTableProvider<T>. This class must orchestrate the translation of the abstract objects provided by quds_db_interface (such as Condition, DataPageQuery, and QueryBuilder) into the engine's specific SQL dialect or query syntax.

For a complete, production-ready implementation of this interface, please refer to the quds_db_sqlite package.