db_dsl library

A Diesel-style query language for Dart.

Declare a table in one line with the app's own model, build queries and writes with the Diesel vocabulary (filter, order, limit, insert, update().set(), delete, transaction), and send them as a documented protocol (PROTOCOL.md) to any Engine: the native offline_first_core bundled by flutter_local_db or dart_db, MemoryEngine for tests, or your own translator. Every operation answers a Result (Ok or Err with a DbError).

This library runs on every platform, the web included; the native runtime lives in package:db_dsl/native.dart.

Classes

AcceptRemote
See ConflictResolution.acceptRemote.
AggregateStatement
SELECT function(field) FROM table WHERE filter; null when no row has a value (for sum and avg, a number).
And
Every operand matches (AND); with no operand, every row matches.
ApplyOutcome
What DbSync.applyRemote did.
Associations
Diesel's associations: load the children of some parents in one query (belonging_to), then group them by parent (grouped_by).
BatchRequest<O>
batch: runs statements in order in one transaction; all commit or none does. Answers one output per statement.
BeginRequest
begin: opens an interactive transaction; answers its id.
ClaimedBatch
A leased batch of envelopes.
ClaimLimits
Limits of DbSync.claim.
Comparison
field <operator> value, with SQL semantics: a missing or null field, or a value of another kind, never matches.
ConflictResolution
How a conflict ends.
ConstraintError
A write broke a rule of the data: a duplicate primary key, a unique index, a missing key, an expectAffectedRows that did not hold, a key whose deletion is not synchronized yet, or a sync operation naming a mutation or conflict that does not match. Nothing was written by the failed statement.
CountStatement
SELECT COUNT(*) FROM table WHERE filter.
Database
A database queried Diesel-style on any Engine: the native engine that flutter_local_db or dart_db bundle (offline_first_core, Rust + LMDB 1.0), MemoryEngine in tests, or a third-party translator.
DbError
A failed database operation, returned as the Err of a Result.
DbOptions
Options for opening a database; they apply when the database is first opened in the process.
DbSync
The offline-first sync of a Database (PROTOCOL.md, "Sync"): its tables declared with syncWith record every write as a change in the same transaction, and these operations move the changes to a server and the server's changes back. The network is yours: the engine only knows what is pending, what is being sent and what the server confirmed.
DbTable<T>
The table of the rows of a model T, declared in one line with the model the app already has:
DefineTableRequest
define_table: creates schema, or adds and removes indexes of an existing table (new indexes are built over its rows). Answers whether anything changed.
DeleteQuery<T>
A delete (delete(table).filter(...)).
DeleteStatement
DELETE FROM table WHERE filter.
DropTableRequest
drop_table: deletes the table name with its rows and indexes. Answers whether it existed.
Engine
Something that answers the db_dsl protocol (PROTOCOL.md).
EngineConnection
An open database of an Engine.
EngineError
The engine itself is missing, incompatible or failed internally.
EngineInfo
Facts about an open database and its engine.
EntitySyncState
The sync state of one row.
Err<T, E>
❌ Represents a failed operation with an error of type E.
ExecuteRequest<O>
execute: runs statement in its own transaction.
ExplainJoinRequest
explain of a join: how the engine would combine the tables of query, without running it.
ExplainRequest
explain: the plan the engine chooses for query, without running it.
Expression
A condition on the rows of a table.
Field<V extends Object>
A field of the rows of a table, compared and read as values of V.
FindQuery<T>
A lookup by primary key: await users.find(1) answers the row, or null when there is none.
FindStatement
The row whose primary key is key, or null.
GroupAggregate
One aggregate of a GroupStatement, stored in each group row as alias.
GroupQuery<T>
Rows grouped by columns, with aggregates per group (Diesel's group_by(...).select((key, count(...)))).
GroupRow
A row of a groupBy: the group key and the aggregates.
GroupStatement
SELECT by, aggregates FROM table WHERE filter GROUP BY by HAVING having ORDER BY order LIMIT limit OFFSET offset.
Index
A secondary index over one or more fields of a table.
IndexSchema
A secondary index of a TableSchema.
InfoRequest
info: facts about the database and its engine.
InsertQuery<T>
An insert (insert_into(table).values(rows)), all rows or none.
InsertStatement
INSERT INTO table VALUES rows, all or none.
JoinClause
One joined table of a JoinStatement.
JoinPlan
How an engine will run a join, without running it.
JoinPlanTable
One table of a JoinPlan.
JoinQuery
Rows of several tables joined by equality (Diesel's inner_join and left_join).
JoinRow
A row of a join: one row of each table, under its name.
JoinStatement
SELECT * FROM from JOIN ... WHERE filter ORDER BY order LIMIT limit OFFSET offset, with each output row combining one row per table under its alias: {"users": {...}, "posts": {...} | null}.
JsonValues
The semantics of JSON values (PROTOCOL.md, "Values").
KeepLocal
See ConflictResolution.keepLocal.
LikePattern
field LIKE pattern, or ILIKE (ASCII case-insensitive) when caseInsensitive. Only strings match.
Membership
field IN (values) (eq_any), or field NOT IN (values) (ne_all) when negated. A missing or null field matches neither.
MemoryConnection
An open database of a MemoryEngine.
MemoryEngine
Answers the protocol in memory, with the observable behavior of offline_first_core: the same results, errors, transactions, savepoints, key order and key limits.
Merged
See ConflictResolution.merged.
Not
The operand does not match (NOT, two-valued: rows the operand does not match, including those where its field is missing or null).
NullCheck
field IS NULL, or IS NOT NULL when not isNull; a missing field is NULL.
Ok<T, E>
✅ Represents a successful operation with a value of type T.
Or
At least one operand matches (OR); with no operand, no row matches.
OrderingTerm
One sort key: a field and its direction.
PendingChange
One open change, as DbSync.pending lists it.
PendingChanges
Open changes of a remote.
PluckQuery<T, V extends Object>
The values of one column (SELECT column), optionally distinct.
ProjectedRow
A row of a projection (project): the selected columns only.
ProjectionQuery<T>
Rows reduced to some columns (SELECT a, b), optionally distinct.
ProtocolEnvelope
Encodes and decodes the JSON envelope an engine answers on the wire: {"v": 1, "ok": <payload>} or {"v": 1, "error": {"code": "<Code>", "message": "..."}}.
ProtocolRequest<O>
A request of the protocol, answered with an output of type O.
PushOutcome
What DbSync.applyPushResult did.
PushResult
What the server answered to a push.
QueryExecutor
Something statements run on: a Database (each statement in its own transaction), a Transaction or a ReadTransaction.
QueryPlan
How an engine will run a query, without running it.
Range
field BETWEEN low AND high (both included), or NOT BETWEEN when negated. The field must compare with both bounds to match either form.
ReadStatement<O>
A statement that only reads.
ReadTransaction
A read-only snapshot (see Database.readTransaction).
Relation<A, B>
A many-to-many relation between rows of from and rows of to, kept in a bridge table of its own (links): one row per linked pair.
One link of a Relation: the keys of a source and of a target.
RemoteChange
One change of the server.
RemotePage
A page of server changes.
RemoteSyncStatus
The checkpoint and counters of a remote.
Result<T, E>
A functional approach to handling results that may be successful or contain errors.
SchemaError
The statement does not fit the schema or the protocol: an unknown table, an invalid definition, a malformed request, a key too large, or a stored row that the table's model cannot read.
SelectQuery<T>
A query over one table, built like Diesel: filter, orFilter, order, thenOrderBy, limit, offset. Awaiting it answers the rows:
SelectStatement
SELECT fields FROM table WHERE filter ORDER BY order LIMIT limit OFFSET offset, optionally DISTINCT.
Statement<O>
A statement on one table, answered with an output of type O.
StorageError
The storage failed or cannot be used: full, corrupt, closed, already open, written by an older format, or an I/O error.
SyncAcknowledgement
The server stored one mutation.
SyncApplyRemoteRequest
sync_apply_remote: applies a page of server changes and its checkpoint in one transaction.
SyncClaimRequest
sync_claim: leases the next eligible changes of remote (one per row, in commit order); answers the batch.
SyncConflict
A server change that met pending local changes (RFC-001 §13.15).
SyncConflictsRequest
sync_conflicts: the open conflicts of remote.
SyncEnvelope
One change to send, with everything the server needs to apply it once.
SyncJson
Readers of protocol JSON for the sync records.
SyncPendingRequest
sync_pending: the open changes of remote, in commit order.
SyncPushResultRequest
sync_push_result: records what the server answered to a push.
SyncRejection
The server refused one mutation.
SyncReleaseRequest
sync_release: makes the deliveries still held by leaseId pending again; answers how many.
SyncResolveRequest
sync_resolve: resolves the conflict conflict if the row version is still expectedRowVersion.
SyncRetryRequest
sync_retry: makes blocked mutations pending again; answers how many were blocked.
SyncStateRequest
sync_state: the sync state of the row key of table; null when the row does not exist and the engine holds no record of it.
SyncStatusRequest
sync_status: the checkpoint and counters of remote.
TableSchema
How a table is stored: its name, primary key, key generation and secondary indexes.
TablesRequest
tables: the definitions of every table.
Transaction
A write transaction (see Database.transaction).
TransactionControlRequest
savepoint, release, rollback_to, commit or rollback on transaction; answers an empty payload.
TransactionError
The transaction cannot go on: it is closed, expired, rollback-only or used the wrong way, or a sync operation raced with another one (a stale checkpoint, a row changed since its conflict was read, a change still being sent). Running the unit of work again is usually the fix.
TransactionExecuteRequest<O>
tx_execute: runs statement inside the open transaction transaction.
UpdateQuery<T>
An update (update(table).filter(...).set(...)).
UpdateStatement
UPDATE table SET set, field = field + delta WHERE filter; the primary key cannot change.
WriteOutput
What a write did: how many rows it affected and, for inserts, the rows as stored (with generated keys).
WriteQuery
A statement that writes. Awaiting it runs it and answers the number of affected rows (await users.insert([ada])); it is also a part of Database.atomicBatch.
WriteStatement
A statement that writes, answered with the affected rows.

Enums

AggregateFunction
The aggregate functions, named as in Diesel.
ComparisonOperator
The operators of a Comparison, named as in Diesel.
DbErrorCode
The exact cause of a DbError.
DeliveryState
The delivery state of an open change.
Durability
How commits reach stable storage.
GroupFunction
The functions of a GroupAggregate.
JoinKind
How a JoinClause treats a row without matches.
OnConflict
What an insert does when a primary key already exists.
PlanAccess
How a plan reaches the rows.
SyncOperation
What a change does to its row.
SyncStateKind
The sync state of a row (RFC-001 §13.3).
TransactionControl
The operations that steer an open transaction.
TransactionMode
What a transaction may do.

Extensions

FutureResultExtensions on Future<Result<T, E>>
Extensions for asynchronous Result operations
ResultCollectionExtensions on Result<List<T>, E>
Extensions for working with Result in collection operations
ResultExtensions on Result<T, E>
Extension methods for Result
TextFieldPatterns on Field<String>
Pattern matching, for text fields.