sqlite library Open a database

Typed SQLite queries on native Dart, Flutter and the web.

Open a temporary database with SqliteOptions.memory, a native file with SqliteOptions.file, or native/browser persistence with SqliteOptions.persistent. The returned database owns its background worker. Import a generated client to access model-specific table getters.

Use package:orm/drivers/sqlite.dart when only a raw driver is needed.

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.
AcquisitionOptions: Limits waiting for a connection, including establishment and initialization. Cancellation after acquisition does not cancel the session callback.
Assignment: One typed column assignment prepared by a writable field.
Backend: Static engine identity used to constrain driver and transaction APIs.
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.
CancellationToken: A cancellation request. Await the operation itself to observe its actual database outcome; completion can win a race with cancellation.
Capabilities Independent SQL drivers: Features a concrete driver can execute for its actual engine and platform.
Change<T>: A patch value that distinguishes omission, assignment and SQL DEFAULT.
CheckSchema: A row CHECK expression. A null name leaves naming to the database.
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.
Column<T> Physical schema metadata: Physical column metadata coupled to the Dart/storage Codec.
ComputedColumn: Database-computed SQL using physical column names.
Cte<R, F extends Fields>: A CTE exports SQL expression identities. Dart mapper properties are not mistaken for SQL columns. ref() accepts only expressions the source selected.
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.
Database Open a database: Typed queries and change notifications over an owned SQL runtime.
Decimal: A finite base-ten value, independent of binary floating point.
DecodeEvent Observe and inspect: Synchronous ORM decoding/mapping and associated row grouping. Excludes SQL, acquisition, compilation, waiting for the consumer and other client work.
Driver Independent SQL drivers: Owns or borrows connection resources for a specific engine B.
ExecutionOptions: Per-operation connection acquisition and statement execution controls.
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.
ForeignKey: A database foreign key described with ordered physical column names.
IndexSchema: A simple index over ordered physical columns.
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.
Mutation<F extends Fields>: A prepared insert, update, or delete that performs no I/O until executed.
Mysql: Type marker for MySQL drivers and sessions.
MysqlTransaction: MySQL isolation and read-only settings applied to the next transaction.
OrderTerm: An expression's sort direction and optional NULL ordering policy.
Postgres: Type marker for PostgreSQL drivers and sessions.
PostgresTransaction: PostgreSQL isolation and read-only settings for one transaction.
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.
Returning<R>: A prepared mutation whose returned SQL rows decode to R.
Selection<T>: A typed result description decoded when its containing query executes.
SqlBuilder: Builds and inspects typed SQL without constructing a driver or a database.
SqlCommand: SQL text and separately bound values. Values are never interpolated into SQL.
SqlConnection Independent SQL drivers: Execution port for one physical connection during an active driver lease.
SqlCursor: Bounded row retrieval tied to the connection lease that opened it.
SqlDatabase Sessions and transactions: Raw SQL execution with owned driver resources and explicit callback scopes.
Sqlite: Type marker for native and browser SQLite drivers and sessions.
SqliteDriver: Owns one SQLite connection and serializes complete connection leases.
SqliteOptions: Chooses an in-memory, native-file, or browser-persistent SQLite database.
SqliteTransaction: SQLite BEGIN mode for an explicit transaction.
SqliteWebOptions: Advanced browser asset overrides. Flutter Web needs no asset configuration.
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.
SqlQueryDefinition<R, F extends Fields>: Generated query definitions reuse table fields and the ordinary Query compiler. Their CTE source makes table mutations invalid before execution.
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.
SqlTemplate: Fixed SQL with :named bound values. Quoted text, identifiers and comments are preserved. This tokenizer is not a SQL parser; use database query checks.
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.
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.
TableSchema Physical schema metadata: Immutable physical table metadata, independent of Dart model identity.
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.

Enums

ComputedStorage: How a database maintains a computed column, subject to engine capabilities.
DecimalRounding: Rounding is explicit; exact rejects a non-zero discarded remainder.
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.
SqlDialect: SQL engine used for quoting, parameter syntax, and capability validation.
SqliteJournal: Native SQLite journal mode; browser persistence manages its own storage.
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

ChangeField on Field<T>: Converts a generated patch input into zero or one SQL assignment.
DecimalExpression on Expr<T>: Exact decimal arithmetic using the selected database's capabilities.
InstantExpression on Expr<T>: Precision control for UTC instant expressions.
InstantPrecision on DateTime: Explicit precision conversion for resolved UTC instants.
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 composition using SQL's three-valued NULL semantics.
QueryStreaming on Query<R, F>: Cursor-backed, demand-driven execution of a typed query.
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.
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.
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<String>: String operations evaluated by the selected database.
TimeExpression on Expr<T>: Precision control for SQL time expressions.
WatchQuery on Query<R, F> Observe and inspect: Re-executes a root database query after relevant committed changes.

Functions

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.
sqlite(SqliteOptions options, {void onQuery(QueryEvent)?, void onAcquire(AcquisitionEvent)?, void onDecode(DecodeEvent)?}) → Future<Database<Sqlite>>: Opens SQLite and returns a typed database that owns its driver and worker.
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.

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.
SqliteFailure: A SQLite error preserving both the primary and extended result codes.

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
Sessions and transactions
runtime
Evolve a schema
migrate
Values and codecs
values
Physical schema metadata
schema_model
Independent SQL drivers
driver
drivers/mariadb
drivers/mysql
drivers/postgres
drivers/sqlite
sqlite_web_worker
Generate and automate
builder
cli
generate
migrate_cli