TransactionHandle class

Convenience wrapper around an active transaction.

TransactionHandle owns the txnId returned by the native odbc_transaction_begin call and exposes the full lifecycle (commit, rollback, savepoints) on a single object.

Two safety nets were added in v3.1:

TransactionHandle.runWithBegin: a static helper that runs a closure inside a transaction, committing on success and attempting rollback on errors. Concurrent native operations may leave the handle retryable.
A best-effort native finalizer that fires when the Dart object is garbage-collected without an explicit commit/rollback. The finalizer reclaims the small native token allocated to track the transaction. The transaction itself is rolled back by the engine when odbc_disconnect runs (already implemented in ffi/mod.rs::odbc_disconnect since v2.0).

Example:

final result = await TransactionHandle.runWithBegin(
  () => native.beginTransactionHandle(connId, isolationLevel.value),
  (txn) async {
    await txn.withSavepoint('sp_first', () async { /* ... */ });
    return 'done';
  },
);

Implemented types

Finalizable

Constructors

TransactionHandle(OdbcConnectionBackend _backend, int _txnId): Creates a new TransactionHandle instance.

Properties

hashCode → int: The hash code for this object.
no setterinherited
isActive → bool: Whether this transaction has not yet been committed or rolled back.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
txnId → int: The transaction identifier returned by odbc_transaction_begin.
no setter

Methods

commit() → bool: Commits the transaction.
createSavepoint(String name) → bool: Creates a savepoint named name inside this transaction.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
releaseSavepoint(String name) → bool: Releases the named savepoint (no-op on SQL Server). The transaction stays active.
rollback() → bool: Rolls back the transaction.
rollbackToSavepoint(String name) → bool: Rolls back to the named savepoint. The transaction itself stays active.
toString() → String: A string representation of this object.
inherited
withSavepoint<T>(String name, Future<T> action()) → Future<T>: Runs action within a savepoint named name. On success the savepoint is released; on any thrown exception we rollback to the savepoint, then rethrow so the caller can decide what to do with the surrounding transaction.

Operators

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

Static Methods

runWithBegin<T>(TransactionHandle? beginFn(), Future<T> action(TransactionHandle txn)) → Future<T>: Runs action inside a fresh transaction obtained from beginFn.