AsyncNativeOdbcConnection class

Non-blocking wrapper around ODBC using a long-lived worker isolate.

Architecture: All FFI/ODBC operations run in a dedicated worker isolate. The main thread stays responsive; no blocking FFI calls run on the UI thread.

How it works

initialize spawns a worker isolate and loads the ODBC driver.
Each operation sends a request (via SendPort) to the worker.
The worker runs the FFI call and sends back the result (via ReceivePort).
The main thread never blocks on ODBC.

Performance

Worker spawn (one-time): ~50–100 ms.
Per-operation overhead: ~1–3 ms.
Parallel queries: N queries complete in the time of the longest (not the sum).

Example

final async = AsyncNativeOdbcConnection();
await async.initialize();

final connId = await async.connect(dsn);
final data = await async.executeQueryParams(connId, 'SELECT 1', []);
await async.disconnect(connId);

async.dispose();

Constructors

AsyncNativeOdbcConnection()

Properties

hashCode → int: The hash code for this object.
no setterinherited
isInitialized → bool: Whether the worker isolate and ODBC environment are initialized.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

beginTransaction(int connectionId, int isolationLevel) → Future<int>: Starts a transaction in the worker for connectionId with isolationLevel. Returns the transaction ID on success.
bulkInsertArray(int connectionId, String table, List<String> columns, Uint8List dataBuffer, int rowCount) → Future<int>: Performs bulk insert on connectionId: table, columns, dataBuffer, rowCount. Returns rows inserted, or negative on error.
catalogColumns(int connectionId, String table) → Future<Uint8List?>: Returns catalog columns for table on connectionId. Binary result or null on error.
catalogTables(int connectionId, {String catalog = '', String schema = ''}) → Future<Uint8List?>: Returns catalog tables for connectionId (optional catalog and schema). Returns binary result or null on error.
catalogTypeInfo(int connectionId) → Future<Uint8List?>: Returns type info for connectionId. Binary result or null on error.
closeStatement(int stmtId) → Future<bool>: Closes the prepared statement stmtId in the worker.
commitTransaction(int txnId) → Future<bool>: Commits the transaction identified by txnId in the worker.
connect(String connectionString, {int timeoutMs = 0}) → Future<int>: Opens a connection in the worker using connectionString.
createSavepoint(int txnId, String name) → Future<bool>: Creates a savepoint name within the transaction txnId in the worker.
disconnect(int connectionId) → Future<bool>: Closes the connection identified by connectionId in the worker.
dispose() → void: Shuts down the worker isolate and releases resources.
executePrepared(int stmtId, List<ParamValue>? params) → Future<Uint8List?>: Executes a prepared statement stmtId in the worker with optional params. Returns the binary result, or null on error.
executeQueryMulti(int connectionId, String sql, {int? maxBufferBytes}) → Future<Uint8List?>: Executes sql on connectionId for multi-result sets in the worker. When maxBufferBytes is set, caps the result buffer size. Returns the binary result, or null on error.
executeQueryParams(int connectionId, String sql, List<ParamValue> params, {int? maxBufferBytes}) → Future<Uint8List?>: Executes sql on connectionId with params in the worker.
getError() → Future<String>: Returns the last error message from the worker (plain text).
getMetrics() → Future<OdbcMetrics?>: Returns ODBC metrics from the worker (query count, errors, latency, etc.).
getStructuredError() → Future<StructuredError?>: Returns the last structured error (message, SQLSTATE, native code), or null if there is no error.
initialize() → Future<bool>: Initializes the worker isolate and ODBC environment.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
poolClose(int poolId) → Future<bool>: Closes pool poolId in the worker.
poolCreate(String connectionString, int maxSize) → Future<int>: Creates a connection pool in the worker. Returns pool ID on success.
poolGetConnection(int poolId) → Future<int>: Obtains a connection from pool poolId. Returns connection ID on success.
poolGetState(int poolId) → Future<({int idle, int size})?>: Returns the current state (size, idle) of pool poolId, or null on error.
poolHealthCheck(int poolId) → Future<bool>: Runs a health check on pool poolId.
poolReleaseConnection(int connectionId) → Future<bool>: Returns connectionId to its pool.
prepare(int connectionId, String sql, {int timeoutMs = 0}) → Future<int>: Prepares sql on connectionId in the worker.
releaseSavepoint(int txnId, String name) → Future<bool>: Releases savepoint name in transaction txnId. Transaction stays active.
rollbackToSavepoint(int txnId, String name) → Future<bool>: Rolls back to savepoint name in transaction txnId. Transaction stays active.
rollbackTransaction(int txnId) → Future<bool>: Rolls back the transaction identified by txnId in the worker.
streamQuery(int connectionId, String sql, {int chunkSize = 1000, int? maxBufferBytes}) → Stream<ParsedRowBuffer>: Runs sql in the worker and yields one ParsedRowBuffer.
streamQueryBatched(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, int? maxBufferBytes}) → Stream<ParsedRowBuffer>: Runs sql in the worker and yields one ParsedRowBuffer.
toString() → String: A string representation of this object.
inherited

Operators

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