SqlDatabase<B extends Backend> class Sessions and transactions

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

The root database owns its driver. Session and transaction callbacks receive borrowed views that expire when their callback finishes. Await every operation before leaving those scopes; active cursors and unfinished work are rejected.

Future<void> renameUser(SqlDatabase<Sqlite> db, int id, String name) async {
  await db.transaction((tx) async {
    await tx.execute(SqlCommand(
      'UPDATE users SET name = ?1 WHERE id = ?2', [name, id],
    ));
  });
}
Available extensions

Constructors

SqlDatabase(Driver<B> driver, {void onQuery(QueryEvent)?, void onAcquire(AcquisitionEvent)?})
Takes ownership of driver; close the root database to release it.

Properties

capabilities → Capabilities
Features and limits exposed by the actual driver and platform.
no setter
dialect → SqlDialect
Connected engine used for SQL syntax and transaction validation.
no setter
driver → Driver<B>
Driver owned by the root database and shared with its borrowed views.
final
hashCode → int
The hash code for this object.
no setterinherited
inSession → bool
Whether this view already holds a connection lease.
no setter
inTransaction → bool
Whether this view belongs to a transaction or savepoint callback.
no setter
onAcquire → void Function(AcquisitionEvent)?
Optional observer for connection acquisition and existing-lease reuse.
final
onQuery → void Function(QueryEvent)?
Optional observer for statements and cursor operations; errors are isolated.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

close() → Future<void>
Stops owned streams and watches, drains pending work, then closes the driver.
discard() → Future<void>
Discards a leased connection after its state can no longer be recovered.
execute(SqlCommand command, {ExecutionOptions options = const ExecutionOptions(), Iterable<String> changedTables = const []}) → Future<SqlResult>
Executes bound SQL and returns raw rows and affected-row metadata.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyChanged(Iterable<String> tables) → void
Notify listeners of external or raw-SQL changes. Rollback discards these notifications; an uncertain COMMIT invalidates conservatively.
run<R>(Future<R> action(SqlConnection), {AcquisitionOptions acquire = const AcquisitionOptions(), OrmException? acquisitionTimeoutError}) → Future<R>
Runs action with an acquired or already leased connection.
savepoint<R>(Future<R> action(SqlDatabase<B> tx)) → Future<R>
Runs nested work inside the current transaction using a database savepoint.
session<R>(Future<R> action(SqlDatabase<B> session), {AcquisitionOptions acquire = const AcquisitionOptions()}) → Future<R>
Retains one connection across transactions and session-scoped operations. The borrowed view expires when the callback returns.
stream(SqlCommand command, {int batchSize = 128, ExecutionOptions options = const ExecutionOptions()}) → Stream<List<Object?>>

Available on SqlDatabase<Backend>, provided by the SqlDatabaseStreaming extension

Streams raw rows, fetching at most batchSize rows per database request.
toString() → String
A string representation of this object.
inherited
transaction<R>(Future<R> action(SqlDatabase<B> tx), {TransactionOptions<B>? options, AcquisitionOptions acquire = const AcquisitionOptions(), Duration? timeout, CancellationToken? cancellation, TransactionRetry? retry}) → Future<R>
Runs action atomically and returns its result after confirmed commit.

Operators

operator ==(Object other) → bool
The equality operator.
inherited