sql library Query and select

Parameterized SQL execution, typed expressions and query inspection.

SqlBuilder compiles a query without opening a connection. Select a scalar, a typed Record with .row, or map selected values into an application model. SqlDatabase executes Sql without model declarations or generation. Typed table queries bind to an ORM view of that same runtime. Named Projection outputs retain their field names through CTE and UNION composition.

Classes

AcquisitionEvent Observe and inspect: Time until a driver lease is granted or acquisition fails. Includes native pool wait/connection setup; it does not separate those driver internals.
Assignment: One typed column assignment prepared by a writable field.
BatchInsert<F extends Fields>: Inserts consecutive rows of the same shape together, splitting at the driver's parameter limit. All chunks share one transaction by default.
BatchReturning<R>: Typed returned rows from a prepared batch insert.
CteFields<F extends Fields>: SQL columns exported by a CTE, referenced through its original expressions.
CursorTerm: One ordering expression paired with its last-seen, encoded cursor value.
DerivedQuery<R, F extends Fields, S extends Selection<R>>: A query over an explicitly named common table expression.
Expr<T>: A typed SQL expression that can also be selected as a result.
Field<T>: A writable column expression that can create mutation assignments.
Fields: Typed expressions belonging to one table occurrence.
MariadbTransaction: MariaDB isolation and read-only settings applied to the next transaction.
Mutation<F extends Fields>: A prepared insert, update, or delete that performs no I/O until executed.
MysqlTransaction: MySQL isolation and read-only settings applied to the next transaction.
Operand<T>: A typed operand accepted by SQL comparison expressions.
OrderTerm: An expression's sort direction and optional NULL ordering policy.
PostgresTransaction: PostgreSQL isolation and read-only settings for one transaction.
Projection<R, O extends ProjectionOutput>: A flat SQL selection with stable, independently registered output slots.
ProjectionFields: Access to validated output slots on a fresh derived SQL occurrence.
ProjectionOutput: A typed field collection exported by a flat SQL projection.
ProjectionType<R, O extends ProjectionOutput>: A fixed flat SQL layout, result assembler, and typed output field factory.
Query<R, F extends Fields>: An immutable typed query bound to a SQL context.
QueryContext: Capabilities and an optional execution binding for typed query descriptions. The SQL layer knows no connection pool, platform adapter or runtime session.
QueryEvent Observe and inspect: Timing and outcome of one SQL statement or cursor operation.
QueryPlan: A non-executing description of one SQL statement and its dependent batches. Bound values are omitted; literal SQL text is retained. A batch SQL template contains one parent key tuple.
ReadField<T>: A selectable column expression with no assignment operations.
Relation<R, F extends Fields>: A relationship is a query description. Constructing or selecting it performs no I/O. List results are loaded in batches on the root query's connection.
RelationLoadPlan: One batch per chunk of distinct non-null parent keys, conditional on data. For nested loads, this rule applies separately to each returned parent batch.
ResultColumn<T>: One result label and its storage/domain codec, with no write constraints.
ResultShape<R>: Required result labels and typed decoding, independent of physical tables. Compositions are validated at construction. Mapping callbacks run once per actual row, never while compiling or binding empty results.
Returning<R>: A prepared mutation whose returned SQL rows decode to R.
SelectedQuery<R, F extends Fields, S extends Selection<R>>: A selected result that retains both source fields and declared output fields.
Selection<T>: A typed result description decoded when its containing query executes.
Slot<T>: A nominal output slot, independent of the expression bound to it.
SlotBinding<T>: One immutable association between a declared slot and its source expression.
Sql: Immutable SQL text, values and composition, with no connection or row cache.
SqlBuilder: Builds and inspects typed SQL without constructing a driver or a database.
SqlCheck: Database preparation evidence; this never proves domain codecs/nullability.
SqlDatabase Sessions and transactions: Raw SQL execution with owned driver resources and explicit callback scopes.
SqliteTransaction: SQLite BEGIN mode for an explicit transaction.
SqlQuery<R>: A reusable SQL statement and typed result contract, independent of a database.
SqlValue<T>: A value encoded once with an explicit storage codec, independent of a session. Mutable bytes are copied. Use a JSON codec for maps and lists.
Table<R, F extends Fields>: A table's physical schema, typed fields and full-row decoder.
TableAlias<R, F extends Fields>: Explicit aliases support self joins and any number of joins without adding a growing number of generic join-result types.
TableQuery<R, F extends Fields>: A table-shaped SQL query with assignment-based update and delete. A selected/mapped result is a Query and cannot be used as a write target.
TableRef: A table occurrence has nominal identity, even when two row records have the same structural Dart type or a query joins the same physical table twice.
TableSet<R, F extends Fields>: Typed access to a table, including full-row reads and prepared inserts.
TransactionOptions Sessions and transactions: Engine-specific settings applied before a transaction callback starts.
TransactionRetry Sessions and transactions: Explicit opt-in: callback logic must be safe to repeat after rollback. The budget counts every scheduled retry, including commit-only retries.
UnionFields<F extends Fields>: References refer to the left operand's exported SQL expressions.
WriteValue<T, F extends Fields>: A reusable typed write intent, before it is bound to a table occurrence.

Enums

Isolation: Requested transaction isolation; exact visibility rules belong to the engine.
NullOrder: Explicit placement of SQL NULL relative to non-null sort values.
QueryOperation: The driver operation measured by a QueryEvent.
SqliteTransactionMode: When SQLite acquires its transaction locks.
ToOneStrategy: How a to-one selection is loaded when its parent query executes.
WindowFrame: Frame used by a window aggregate.

Extensions

ColumnSql on Column<T>: Reuses a physical column's codec for raw parameters and result labels.
DecimalExpression on Expr<T>: Exact decimal arithmetic using the selected database's capabilities.
FieldSql on ReadField<T>: Reuses a table field's codec without capturing its alias or connection.
InstantExpression on Expr<T>: Precision control for UTC instant expressions.
KeysetQuery on Query<R, F>: Stable keyset pagination for a filtered table query.
LocalDateTimeExpression on Expr<T>: Precision control for local timestamps without a time zone.
NumericExpression on Expr<T>: SQL arithmetic and aggregation for Dart numeric values.
NumericField on Field<T>: Atomic numeric updates evaluated inside the database statement.
Predicate on Expr<bool?>: Boolean negation using SQL's three-valued NULL semantics.
ProjectedSql on SelectedQuery<R, F, Projection<R, O>>: SQL composition that preserves a flat projection's named output fields.
QueryCtes on Query<R, F>: Creates a CTE from selections without declared named output fields.
QueryStreaming on Query<R, F>: Cursor-backed, demand-driven execution of a typed query.
Result2 on (ResultShape<A>, ResultShape): Combines 2 typed result descriptions, including nested result shapes.
Result3 on (ResultShape<A>, ResultShape, ResultShape<C>): Combines 3 typed result descriptions, including nested result shapes.
Result4 on (ResultShape<A>, ResultShape, ResultShape<C>, ResultShape<D>): Combines 4 typed result descriptions, including nested result shapes.
Result5 on (ResultShape<A>, ResultShape, ResultShape<C>, ResultShape<D>, ResultShape<E>): Combines 5 typed result descriptions, including nested result shapes.
Result6 on (ResultShape<A>, ResultShape, ResultShape<C>, ResultShape<D>, ResultShape<E>, ResultShape<F>): Combines 6 typed result descriptions, including nested result shapes.
RuntimeSqlExecution on SqlDatabase<Backend>: Parameterized SQL on the owning runtime or its borrowed session.
Selection2 on (Selection<A>, Selection): Composes two independently typed selections into one decoded result.
Selection3 on (Selection<A>, Selection, Selection<C>): Composes three independently typed selections into one decoded result.
Selection4 on (Selection<A>, Selection, Selection<C>, Selection<D>): Composes four independently typed selections into one decoded result.
Selection5 on (Selection<A>, Selection, Selection<C>, Selection<D>, Selection<E>): Composes five independently typed selections into one decoded result.
Selection6 on (Selection<A>, Selection, Selection<C>, Selection<D>, Selection<E>, Selection<F>): Composes six independently typed selections into one decoded result.
SelectQuery on Query<R, F>: Chooses decoded results while retaining a concrete selection's SQL evidence.
SetQueries on Query<R, F>: SQL set operations over matching scalar or positional Record projections.
SqlDatabaseStreaming on SqlDatabase<Backend> Sessions and transactions: Demand-driven raw-row streaming with a bounded database cursor.
SqlExecution on QueryContext: Executes reusable SQL on the current database, session or transaction.
SqlRow2 on (Expr<A>, Expr): Projects two SQL expressions as a positional Dart Record.
SqlRow3 on (Expr<A>, Expr, Expr<C>): Projects three SQL expressions as a positional Dart Record.
SqlRow4 on (Expr<A>, Expr, Expr<C>, Expr<D>): Projects four SQL expressions as a positional Dart Record.
SqlRow5 on (Expr<A>, Expr, Expr<C>, Expr<D>, Expr<E>): Projects five SQL expressions as a positional Dart Record.
SqlRow6 on (Expr<A>, Expr, Expr<C>, Expr<D>, Expr<E>, Expr<F>): Projects six SQL expressions as a positional Dart Record.
TextExpression on Expr<T>: String operations evaluated by the selected database, preserving SQL NULL.
TimeExpression on Expr<T>: Precision control for SQL time expressions.
WriteValueField on Field<T>: Binds a typed input intent using the ordinary mutation assignment path.

Functions

allOf(Iterable<Expr<bool?>> predicates) → Expr<bool?>: Requires every predicate to be SQL TRUE; an empty group is TRUE.
anyOf(Iterable<Expr<bool?>> predicates) → Expr<bool?>: Requires at least one predicate to be SQL TRUE; an empty group is FALSE.
checkSqlQuery<R>(SqlDatabase<Backend> db, SqlQuery<R> query) → Future<SqlCheck>: Prepares a SELECT/WITH/VALUES query without executing application expressions. Uses a temporary projected subquery only for checking, never for execution. DML, including RETURNING, is outside this check's scope.
fields(Map<String, Selection<Object?>> selected) → Selection<Map<String, Object?>>: Runtime field selection deliberately returns dynamic values.
rank({List<Expr<Object?>> partitionBy = const [], required List<OrderTerm> orderBy}) → Expr<int>: Builds one-based SQL rank, with ties sharing a rank and leaving later gaps.
rowNumber({List<Expr<Object?>> partitionBy = const [], List<OrderTerm> orderBy = const []}) → Expr<int>: Builds a one-based SQL row number within each partition.
sql<T>(List<String> parts, List<Expr<Object?>> values, Codec<T> codec) → Expr<T>: parts are trusted SQL, values are expressions. Never put user input in parts.
value<T>(T value, Codec<T> codec) → Expr<T>: Creates a bound SQL value using an explicit storage codec.

Typedefs

PlannedColumn = ({String codecType, String? column, int index, bool presence, String? table}): A physical SQL output slot, including association keys and presence markers. Expressions without a direct column source have null table/column names.
PlannedJoin = ({bool left, bool relation, String table}): A joined table name, join kind and whether a relation introduced it.

orm package

Topics
Open a database
Declare models
Query and select
Sessions and transactions
Evolve a schema
Values and codecs
Observe and inspect
Generate and automate
Libraries
Open a database
mariadb
mysql
orm
postgres
sqlite
Declare models
schema
Query and select
sql
Evolve a schema
migrate
Values and codecs
values
Physical schema metadata
schema_model
Independent SQL drivers
driver
sqlite_web_worker
Generate and automate
builder
cli
config
generate
migrate_cli