runtime library Sessions and transactions

Connection leases, transactions and streaming for parameterized SQL.

Construct SqlDatabase with a driver when an application needs raw SQL without typed queries. The database owns the driver; session and transaction callbacks borrow connections and must not escape their callback lifetimes.

Classes

AcquisitionEvent

Time until a driver lease is granted or acquisition fails. Includes native pool wait/connection setup; it does not separate those driver internals.

AcquisitionOptions

Limits waiting for a connection, including establishment and initialization. Cancellation after acquisition does not cancel the session callback.

Backend

Static engine identity used to constrain driver and transaction APIs.

CancellationToken

A cancellation request. Await the operation itself to observe its actual database outcome; completion can win a race with cancellation.

Capabilities

Features a concrete driver can execute for its actual engine and platform.

Codec<T>

Converts a typed Dart value to database storage and decodes it on reads.

Codecs

Built-in conversions for SQL scalar values, JSON, and exact numeric types.

Decimal

A finite base-ten value, independent of binary floating point.

Driver<B extends Backend>

Owns or borrows connection resources for a specific engine B.

ExecutionOptions

Per-operation connection acquisition and statement execution controls.

LocalDate

A Gregorian calendar date, without a time or timezone. Year 0 is 1 BC; negative years use astronomical numbering.

LocalDateTime

Calendar date and wall-clock time, with no timezone or implied UTC instant.

LocalTime

A wall-clock time at microsecond resolution, including the endpoint 24:00. The fourth constructor argument is the full fractional second (0..999999).

Mariadb

Type marker for MariaDB drivers and sessions.

MariadbTransaction

MariaDB isolation and read-only settings applied to the next transaction.

Mysql

Type marker for MySQL drivers and sessions.

MysqlTransaction

MySQL isolation and read-only settings applied to the next transaction.

Postgres

Type marker for PostgreSQL drivers and sessions.

PostgresTransaction

PostgreSQL isolation and read-only settings for one transaction.

QueryEvent

Timing and outcome of one SQL statement or cursor operation.

SqlCommand

SQL text and separately bound values. Values are never interpolated into SQL.

SqlConnection

Execution port for one physical connection during an active driver lease.

SqlCursor

Bounded row retrieval tied to the connection lease that opened it.

SqlDatabase<B extends Backend>

Raw SQL execution with owned driver resources and explicit callback scopes.

Sqlite

Type marker for native and browser SQLite drivers and sessions.

SqliteTransaction

SQLite BEGIN mode for an explicit transaction.

SqlJson

A non-SQL-null JSON document. Its value may itself be JSON null. Drivers use this envelope for parsed JSON, including JSON string scalars.

SqlReal

Explicit floating-point SQL input. JavaScript cannot distinguish an integral double from int by runtime type; this preserves the SQL intention.

SqlResult

Raw row values and write metadata returned by a completed driver operation.

TransactionOptions<B extends Backend>

Engine-specific settings applied before a transaction callback starts.

TransactionRetry

Explicit opt-in: callback logic must be safe to repeat after rollback. The budget counts every scheduled retry, including commit-only retries.

Enums

DecimalRounding

Rounding is explicit; exact rejects a non-zero discarded remainder.

Isolation

Requested transaction isolation; exact visibility rules belong to the engine.

QueryOperation

The driver operation measured by a QueryEvent.

SqlDialect

SQL engine used for quoting, parameter syntax, and capability validation.

SqliteTransactionMode

When SQLite acquires its transaction locks.

Extensions

InstantPrecision on DateTime

Explicit precision conversion for resolved UTC instants.

SqlDatabaseStreaming on SqlDatabase<Backend>

Demand-driven raw-row streaming with a bounded database cursor.

Exceptions / Errors

OrmException

An ORM failure with a stable machine-readable code and optional cause.

SqlFailure

Adapter classification. Retrying also requires a confirmed rollback and an explicitly repeatable application callback; these flags alone are not enough.