NativeOdbcConnection class

Native ODBC connection implementation using FFI bindings.

Provides direct access to the Rust-based ODBC engine through FFI. This is the low-level implementation that handles all native ODBC operations including connections, queries, transactions, prepared statements, connection pooling, and streaming.

Example:

final native = NativeOdbcConnection();
native.initialize();
final connId = native.connect('DSN=MyDatabase');
Implemented types

Constructors

NativeOdbcConnection()
Creates a new NativeOdbcConnection instance.
NativeOdbcConnection.testing(OdbcNative native)
Creates an instance backed by injected native (unit tests only).

Properties

auditLogger → OdbcAuditLogger
Typed wrapper for native audit APIs.
no setterinherited
hashCode → int
The hash code for this object.
no setterinherited
isInitialized → bool
Whether the ODBC environment has been initialized.
no setterinherited
native → OdbcNative
Internal — exposes the underlying bindings.OdbcNative to helpers like XaTransactionHandle that need to drive the FFI directly. Not part of the public API; callers should use the high-level methods on this class.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
supportsAsyncExecuteApi → bool
Whether the loaded native library supports async execute FFI endpoints.
no setterinherited
supportsAsyncExecuteParamsApi → bool
Whether async execute also supports serialized parameter buffers.
no setterinherited
supportsAsyncStreamApi → bool
Whether the loaded native library supports async stream FFI endpoints.
no setterinherited
supportsAuditApi → bool
Whether the loaded native library supports audit FFI endpoints.
no setterinherited
supportsConnectionDbmsInfoApi → bool
Whether the loaded native library exposes live DBMS introspection (v2.1 odbc_get_connection_dbms_info).
no setterinherited
supportsDriverCapabilitiesApi → bool
Whether the loaded native library supports driver capabilities FFI API.
no setterinherited
supportsExecuteQueryMultiParams → bool
Whether the loaded native library exports odbc_exec_query_multi_params (added in v3.2.0).
no setterinherited
supportsMetadataCacheApi → bool
Whether the loaded native library supports metadata cache FFI endpoints.
no setterinherited
supportsResultEncodingOptions → bool
Whether parameterized query execution can request columnar result encodings. When false, callers fall back to row-major v1.
no setterinherited
supportsStreamQueryMulti → bool
Whether the loaded native library exports the M8 streaming multi-result FFIs (added in v3.3.0).
no setterinherited
supportsStructuredErrorForConnection → bool
Whether the native library supports per-connection structured error API.
no setterinherited
supportsTransactionAccessMode → bool
True when the loaded native library supports odbc_transaction_begin_v2 (Sprint 4.1, the accessMode parameter of beginTransaction). When false, accessMode is silently ignored and every transaction is READ WRITE.
no setterinherited
supportsTransactionLockTimeout → bool
True when the loaded native library supports odbc_transaction_begin_v3 (Sprint 4.2, the lockTimeoutMs parameter of beginTransaction). When false, lockTimeoutMs is silently ignored and every transaction uses the engine default lock timeout.
no setterinherited
supportsXa → bool
True when the loaded native library supports the XA / 2PC FFI family (Sprint 4.3). Callers should gate on this before invoking xaStart / xaRecover / xaResumePrepared; older binaries throw UnsupportedError.
no setterinherited

Methods

asyncCancel(int requestId) → bool
Best-effort cancellation for an async request.
inherited
asyncFree(int requestId) → bool
Frees async request resources.
inherited
asyncGetResult(int requestId) → Uint8List?
Retrieves binary result for a completed async request.
inherited
asyncPoll(int requestId) → int?
Polls async request status: 0 pending, 1 ready, -1 error, -2 cancelled.
inherited
beginTransaction(int connectionId, int isolationLevel, {int savepointDialect = 0, int accessMode = 0, int lockTimeoutMs = 0}) → int
Begins a new transaction with the specified isolation level.
inherited
beginTransactionHandle(int connectionId, int isolationLevel, {int savepointDialect = 0, int accessMode = 0, int lockTimeoutMs = 0}) → TransactionHandle?
Begins a new transaction and returns a TransactionHandle wrapper.
inherited
bulkInsertArray(int connectionId, String table, List<String> columns, Uint8List dataBuffer, int rowCount) → int
Performs a bulk insert operation.
inherited
bulkInsertParallel(int poolId, String table, List<String> columns, Uint8List dataBuffer, int parallelism) → int
Performs parallel bulk insert through poolId.
inherited
cancelStatement(int stmtId) → bool
Requests cancellation of a prepared statement execution.
inherited
catalogColumns(int connectionId, String table) → Uint8List?
inherited
catalogForeignKeys(int connectionId, String table) → Uint8List?
inherited
catalogIndexes(int connectionId, String table) → Uint8List?
inherited
catalogPrimaryKeys(int connectionId, String table) → Uint8List?
inherited
catalogQuery(int connectionId) → CatalogQuery
Creates a CatalogQuery wrapper for database catalog queries.
inherited
catalogTables(int connectionId, {String catalog = '', String schema = ''}) → Uint8List?
inherited
catalogTypeInfo(int connectionId) → Uint8List?
inherited
clearAllStatements() → int
inherited
clearAuditEvents() → bool
Clears in-memory native audit events.
inherited
clearMetadataCache() → bool
Clears metadata cache entries.
inherited
clearStatementCache() → bool
Clears the prepared statement cache.
inherited
closeStatement(int stmtId) → bool
inherited
commitTransaction(int txnId) → bool
inherited
connect(String connectionString) → int
Establishes a new database connection.
inherited
connectWithTimeout(String connectionString, int timeoutMs) → int
Establishes a connection with a login timeout.
inherited
createConnectionPool(String connectionString, int maxSize, {PoolOptions? options}) → ConnectionPool?
Creates a new connection pool and returns a ConnectionPool wrapper.
inherited
createSavepoint(int txnId, String name) → bool
inherited
detectDriver(String connectionString) → String?
Detects the database driver from a connection string.
inherited
disconnect(int connectionId) → bool
Closes and disconnects a connection.
inherited
dispose() → void
Disposes of native resources.
inherited
executeAsyncStart(int connectionId, String sql) → int?
Starts non-blocking query execution and returns async request ID.
inherited
executeAsyncStartParams(int connectionId, String sql, Uint8List? serializedParams, {ResultEncoding resultEncoding = ResultEncoding.rowMajor}) → int?
Starts non-blocking parameterized query execution.
inherited
executePrepared(int stmtId, List<ParamValue>? params, int timeoutOverrideMs, int fetchSize, {int? maxBufferBytes}) → Uint8List?
inherited
executePreparedRaw(int stmtId, Uint8List? serializedParams, int timeoutOverrideMs, int fetchSize, {int? maxBufferBytes}) → Uint8List?
Executes a prepared statement with params already serialized (bytes).
inherited
executeQueryMulti(int connectionId, String sql, {int? maxBufferBytes}) → Uint8List?
Executes a SQL query that returns multiple result sets.
inherited
executeQueryMultiParams(int connectionId, String sql, Uint8List? paramsBuffer, {int? maxBufferBytes}) → Uint8List?
Executes a parameterised batch SQL that may return multiple result sets.
inherited
executeQueryParams(int connectionId, String sql, List<ParamValue> params, {int? maxBufferBytes, ResultEncoding resultEncoding = ResultEncoding.rowMajor}) → Uint8List?
Executes a SQL query with parameters.
inherited
executeQueryParamsRaw(int connectionId, String sql, Uint8List? serializedParams, {int? maxBufferBytes, ResultEncoding resultEncoding = ResultEncoding.rowMajor}) → Uint8List?
Executes a parameterized query with params already serialized (bytes).
inherited
getAuditEventsJson({int limit = 0}) → String?
Gets audit events as JSON payload.
inherited
getAuditStatusJson() → String?
Gets audit status as JSON payload.
inherited
getCacheMetrics() → PreparedStatementMetrics?
inherited
getConnectionDbmsInfoJson(int connectionId) → String?
Returns the live DBMS introspection JSON for connectionId, or null when the call fails or the API is unavailable. Use the high-level OdbcDriverCapabilities.getDbmsInfoForConnection to obtain a typed DbmsInfo instead of raw JSON.
inherited
getDriverCapabilities(String connectionString) → DriverCapabilities?
Returns typed driver capabilities from connectionString, or null when API is unavailable or invalid.
inherited
getDriverCapabilitiesJson(String connectionString) → String?
Returns driver capabilities payload as JSON, or null on failure.
inherited
getError() → String
Gets the last error message from the native engine.
inherited
getMetadataCacheStatsJson() → String?
Returns metadata cache stats JSON payload.
inherited
getMetrics() → OdbcMetrics?
inherited
getStructuredError() → StructuredError?
Gets structured error information including SQLSTATE and native code.
inherited
getStructuredErrorForConnection(int connectionId) → StructuredError?
Gets structured error for a specific connection (per-connection isolation).
inherited
getVersion() → Map<String, String>?
Gets performance and operational metrics.
inherited
initialize() → bool
Initializes the ODBC environment.
inherited
metadataCacheEnable({required int maxEntries, required int ttlSeconds}) → bool
Enables metadata cache in native engine.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
poolClose(int poolId) → bool
inherited
poolCreate(String connectionString, int maxSize, {PoolOptions? options}) → int
Creates a new connection pool.
inherited
poolCreateWithOptions(String connectionString, int maxSize, {String? optionsJson}) → int
Creates a pool from a pre-encoded native options JSON payload.
inherited
poolGetConnection(int poolId) → int
inherited
poolGetState(int poolId) → ({int idle, int size})?
inherited
poolGetStateJson(int poolId) → Map<String, dynamic>?
Returns pool state telemetry payload as JSON, or null on failure.
inherited
poolHealthCheck(int poolId) → bool
inherited
poolReleaseConnection(int connectionId) → bool
inherited
poolSetSize(int poolId, int newMaxSize) → bool
inherited
prepare(int connectionId, String sql, {int timeoutMs = 0}) → int
Prepares a SQL statement for execution.
inherited
prepareStatement(int connectionId, String sql, {int timeoutMs = 0}) → PreparedStatement?
Prepares a SQL statement and returns a PreparedStatement wrapper.
inherited
prepareStatementNamed(int connectionId, String sql, {int timeoutMs = 0}) → PreparedStatement?
Prepares a SQL statement with named parameters and returns a PreparedStatement wrapper that supports executeNamed.
inherited
releaseSavepoint(int txnId, String name) → bool
inherited
rollbackToSavepoint(int txnId, String name) → bool
inherited
rollbackTransaction(int txnId) → bool
inherited
setAuditEnabled({required bool enabled}) → bool
Enables/disables native audit event collection.
inherited
setLogLevel(int level) → void
Sets native engine log verbosity (0=off, 5=trace).
inherited
streamAsync(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, Duration pollInterval = const Duration(milliseconds: 10), ResultEncoding resultEncoding = ResultEncoding.rowMajor, bool lazyStrings = false}) → Stream<ParsedRowBuffer>
Poll-based async batched streaming via odbc_stream_start_async.
inherited
streamCancel(int streamId) → bool
Requests cancellation for a low-level native stream.
inherited
streamClose(int streamId) → bool
Closes a low-level native stream.
inherited
streamFetch(int streamId) → StreamFetchResult
Fetches the next chunk for a low-level native stream.
inherited
streamMultiStartAsync(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, int resultEncodingWire = 0}) → int?
Async variant of streamMultiStartBatched. Combine with streamPollAsync for non-blocking readiness.
inherited
streamMultiStartBatched(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, int resultEncodingWire = 0}) → int?
Starts a streaming multi-result batch in batched mode and returns the new stream id (or null on failure / unsupported native lib). Use streamFetch / streamCancel / streamClose to drive it. When resultEncodingWire is non-zero and the native library exports odbc_stream_multi_start_batched_options, result-set frames use columnar v2 wire layout.
inherited
streamPollAsync(int streamId) → int?
Polls async stream status: 0 pending, 1 ready, 2 done, -1 error, -2 cancelled.
inherited
streamQuery(int connectionId, String sql, {int chunkSize = 1000}) → Stream<ParsedRowBuffer>
Executes a SQL query and returns results as a batched stream.
inherited
streamQueryBatched(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, ResultEncoding resultEncoding = ResultEncoding.rowMajor, bool lazyStrings = false}) → Stream<ParsedRowBuffer>
Executes a SQL query and returns results as a batched stream.
inherited
streamQueryBuffer(int connectionId, String sql, {int chunkSize = 1000, bool lazyStrings = false}) → Stream<ParsedRowBuffer>
Legacy buffer-mode streaming via odbc_stream_start. Materialises the full result in native memory before yielding a single parsed chunk. Prefer streamQuery or streamQueryBatched for large result sets.
inherited
streamQueryColumnarBatched(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, bool lazyStrings = false, ResultEncoding resultEncoding = ResultEncoding.columnar}) → Stream<TypedColumnarResult>
Like streamQueryBatched but decodes columnar v2 frames directly to TypedColumnarResult without a row-major intermediate.
inherited
streamStart(int connectionId, String sql, {int chunkSize = 1000}) → int
Starts a low-level streaming query and returns a native stream ID.
inherited
streamStartAsync(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, int resultEncodingWire = 0}) → int?
Starts async stream and returns stream ID.
inherited
streamStartBatched(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, int resultEncodingWire = 0}) → int
Starts a low-level batched streaming query and returns stream ID.
inherited
toString() → String
A string representation of this object.
inherited
validateConnectionString(String connectionString) → String?
Validates connection string format without opening a connection.
inherited
xaRecover(int connectionId) → List<Xid>?
xa_recover: list every XID currently in the XaState.prepared state on the resource manager. Used after process restart to discover branches awaiting a Phase 2 decision.
inherited
xaResumePrepared(int connectionId, Xid xid) → XaTransactionHandle?
Resume a previously prepared xid — rebuilds an XaTransactionHandle in the XaState.prepared state for crash- recovery scenarios. Returns null on failure.
inherited
xaStart(int connectionId, Xid xid) → XaTransactionHandle?
xa_start: open a new XA branch on connectionId with the given xid. Returns a live XaTransactionHandle in the XaState.active state on success, null on failure (call getStructuredError to inspect the cause).
inherited

Operators

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