session<R> method

Future<R> session<R>(Future<R> action(SqlDatabase<B> session), { AcquisitionOptions acquire = const AcquisitionOptions(), })

Retains one connection across transactions and session-scoped operations. The borrowed view expires when the callback returns.

A session does not begin a transaction. Use its transaction method for atomic work; nested sessions are rejected. Returning with pending work or an active stream fails and drains the borrowed view before lease release.

Implementation

Future<R> session<R>(
  Future<R> Function(SqlDatabase<B> session) action, {
  AcquisitionOptions acquire = const AcquisitionOptions(),
}) {
  if (_connection != null) {
    throw const OrmException(
      'SESSION.NESTED',
      'This session already owns a connection lease.',
    );
  }
  return run((connection) async {
    final session = SqlDatabase<B>._(
      driver,
      connection,
      onQuery,
      onAcquire: onAcquire,
      changeListeners: _changeListeners,
      transaction: false,
    );
    try {
      final result = await action(session);
      session._active = false;
      if (session._pending.isNotEmpty ||
          session._streams.isNotEmpty ||
          session._cursors.isNotEmpty) {
        throw const OrmException(
          'SESSION.UNAWAITED',
          'Await all work before releasing a session.',
        );
      }
      return result;
    } finally {
      final cleanup = await session._drain();
      if (cleanup != null) {
        await connection.invalidate();
        throw cleanup;
      }
    }
  }, acquire: acquire);
}