OdbcNative class

Native ODBC bindings wrapper.

Provides a high-level Dart interface to the native ODBC engine through FFI bindings. Handles connection management, queries, transactions, prepared statements, connection pooling, and streaming.

Constructors

OdbcNative()
Creates a new OdbcNative instance.
OdbcNative.withBindings(OdbcBindings injected)
Creates an instance backed by injected bindings (unit tests only).

Properties

hashCode → int
The hash code for this object.
no setterinherited
rawBindings → OdbcBindings
Read-only access to the raw bindings. Use only for new capabilities implemented in companion modules (e.g. driver_capabilities_v3.dart).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sqlCacheStats → ({int evictions, int hits, int misses})
Diagnostic counters for the SQL pointer cache. Useful from benchmarks to verify that hot paths actually hit. Not part of the public API surface; consider it advisory.
no setter
supportsAsyncExecuteApi → bool
True when the loaded native library exposes async execute FFI APIs.
no setter
supportsAsyncExecuteParamsApi → bool
True when async execute also supports serialized parameter buffers.
no setter
supportsAsyncExecuteParamsOptionsApi → bool
True when async parameterized execution supports ResultEncoding (v3.9+).
no setter
supportsAsyncMultiResultStream → bool
no setterinherited
supportsAsyncStreamApi → bool
True when the loaded native library exposes async stream FFI APIs.
no setter
supportsAuditApi → bool
True when the loaded native library exposes the audit FFI API.
no setter
supportsConnectionDbmsInfoApi → bool
True when the loaded native library exposes the v2.1 live DBMS introspection FFI (odbc_get_connection_dbms_info).
no setterinherited
supportsDriverCapabilitiesApi → bool
True when the loaded native library exposes driver capabilities FFI API.
no setter
supportsExecQueryMultiParams → bool
Whether the loaded native library exports odbc_exec_query_multi_params (added in v3.2.0).
no setterinherited
supportsMetadataCacheApi → bool
True when the loaded native library exposes metadata cache FFI APIs.
no setter
supportsMultiResultStream → bool
Whether the loaded native library exports the M8 streaming multi-result FFIs (added in v3.3.0).
no setterinherited
supportsMultiResultStreamEncodingOptions → bool
True when multi-result batched streaming accepts ResultEncoding.
no setter
supportsPoolCreateWithOptions → bool
Whether the loaded native library exposes the v3.0 odbc_pool_create_with_options entry point.
no setterinherited
supportsResultEncodingOptions → bool
True when the native library exposes result encoding options for direct parameterized query execution.
no setter
supportsStreamAsyncEncodingOptions → bool
True when async batched streaming accepts ResultEncoding on the wire.
no setter
supportsStreamResultEncodingOptions → bool
True when batched streaming accepts ResultEncoding on the wire (v4.2+).
no setter
supportsStructuredErrorForConnection → bool
Whether the native library exposes per-connection structured error API.
no setterinherited
supportsTransactionAccessMode → bool
True when the loaded native library exports odbc_transaction_begin_v2 (Sprint 4.1). Callers that intend to pass a non-default accessMode should gate on this flag; older binaries fall back to v1 and READ ONLY becomes a silent no-op.
no setterinherited
supportsTransactionLockTimeout → bool
True when the loaded native library exports odbc_transaction_begin_v3 (Sprint 4.2). Callers that intend to pass a non-default lockTimeoutMs should gate on this flag; older binaries fall back to v2/v1 and the timeout becomes a silent no-op (engine default).
no setterinherited
supportsXa → bool
True when the loaded native library exports the XA / 2PC FFI family (Sprint 4.3). Callers should gate on this before using any of the xaStart / xaPrepare / etc. methods — 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 async query result payload for a completed request.
inherited
asyncPoll(int requestId) → int?
Polls async request status.
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 a parallel bulk insert operation through poolId.
inherited
cancelStatement(int stmtId) → bool
Cancels a prepared statement execution.
inherited
catalogColumns(int connectionId, String table) → Uint8List?
Queries the database catalog for column information.
inherited
catalogForeignKeys(int connectionId, String table) → Uint8List?
Queries the database catalog for foreign key information.
inherited
catalogIndexes(int connectionId, String table) → Uint8List?
Queries the database catalog for index information.
inherited
catalogPrimaryKeys(int connectionId, String table) → Uint8List?
Queries the database catalog for primary key information.
inherited
catalogTables(int connectionId, {String catalog = '', String schema = ''}) → Uint8List?
Queries the database catalog for table information.
inherited
catalogTypeInfo(int connectionId) → Uint8List?
Queries the database catalog for data type information.
inherited
clearAllStatements() → int
Clears all prepared statements.
inherited
clearAuditEvents() → bool
Clears all in-memory native audit events.
inherited
clearStatementCache() → bool
Clears the prepared statement cache.
inherited
closeStatement(int stmtId) → bool
Closes and releases a prepared statement.
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
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.
execQuery(int connectionId, String sql, {int? maxBufferBytes}) → Uint8List?
Executes a SQL query and returns binary result data.
inherited
execQueryMulti(int connectionId, String sql, {int? maxBufferBytes}) → Uint8List?
Executes a SQL query that returns multiple result sets.
inherited
execQueryMultiParams(int connectionId, String sql, Uint8List? paramsBuffer, {int? maxBufferBytes}) → Uint8List?
Executes a parameterised batch SQL that may return multiple result sets.
inherited
execQueryParams(int connectionId, String sql, Uint8List? params, {int? maxBufferBytes, ResultEncoding resultEncoding = ResultEncoding.rowMajor}) → Uint8List?
Executes a SQL query with binary parameters.
inherited
execQueryParamsTyped(int connectionId, String sql, List<ParamValue> params, {int? maxBufferBytes, ResultEncoding resultEncoding = ResultEncoding.rowMajor}) → Uint8List?
Executes a SQL query with typed parameters.
inherited
execute(int stmtId, [Uint8List? params, int timeoutOverrideMs = 0, int fetchSize = 1000, int? maxBufferBytes]) → Uint8List?
Executes a prepared statement with optional binary parameters.
inherited
executeAsyncStart(int connectionId, String sql) → int?
Starts non-blocking query execution and returns async request ID.
inherited
executeAsyncStartParams(int connectionId, String sql, Uint8List? params, {ResultEncoding resultEncoding = ResultEncoding.rowMajor}) → int?
Starts non-blocking parameterized query execution.
inherited
executeTyped(int stmtId, [List<ParamValue>? params, int timeoutOverrideMs = 0, int fetchSize = 1000, int? maxBufferBytes]) → Uint8List?
Executes a prepared statement with typed parameters.
inherited
execWithBuffer(int op(Pointer<Uint8> buf, int bufLen, Pointer<Uint32> outWritten)) → Uint8List?
Re-export of the buffer-allocation helper so capability modules can reuse the same retry/grow logic used internally.
getAuditEventsJson({int limit = 0}) → String?
Gets audit events encoded as UTF-8 JSON array.
inherited
getAuditStatusJson() → String?
Gets current audit status encoded as UTF-8 JSON object.
inherited
getCacheMetrics() → PreparedStatementMetrics?
Gets prepared statement cache metrics.
inherited
getConnectionDbmsInfoJson(int connectionId) → String?
Live DBMS introspection (v2.1). Returns the JSON document produced by odbc_get_connection_dbms_info for the given connection id, or null when the FFI is unavailable / the call fails.
inherited
getDriverCapabilitiesJson(String connectionString) → String?
Gets driver capabilities from connection string as UTF-8 JSON object.
inherited
getError() → String
Gets the last error message from the native engine.
inherited
getMetrics() → OdbcMetrics?
Gets performance and operational metrics.
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>?
Returns engine version (api + abi) for client compatibility checks.
init() → bool
Initializes the ODBC environment.
metadataCacheClear() → bool
Clears all metadata cache entries.
inherited
metadataCacheEnable({required int maxEntries, required int ttlSeconds}) → bool
Enables or reconfigures metadata cache in native engine.
inherited
metadataCacheStatsJson() → String?
Returns metadata cache statistics as JSON payload.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
poolClose(int poolId) → bool
Closes the connection pool and releases all connections.
inherited
poolCreate(String connectionString, int maxSize) → int
Creates a new connection pool.
inherited
poolCreateWithOptions(String connectionString, int maxSize, {String? optionsJson}) → int
Creates a pool with explicit eviction/timeout options (v3.0).
inherited
poolGetConnection(int poolId) → int
Gets a connection from the pool.
inherited
poolGetState(int poolId) → ({int idle, int size})?
Gets the current state of the connection pool.
inherited
poolGetStateJson(int poolId) → Map<String, dynamic>?
Gets pool state as JSON (detailed metrics for monitoring).
inherited
poolHealthCheck(int poolId) → bool
Performs a health check on the connection pool.
inherited
poolReleaseConnection(int connectionId) → bool
Releases a connection back to the pool.
inherited
poolSetSize(int poolId, int newMaxSize) → bool
Resizes the pool by recreating it with newMaxSize.
inherited
prepare(int connectionId, String sql, {int timeoutMs = 0}) → int
Prepares a SQL statement for execution.
inherited
savepointCreate(int txnId, String name) → bool
Creates a savepoint within an active transaction.
inherited
savepointRelease(int txnId, String name) → bool
Releases a savepoint. The transaction remains active.
inherited
savepointRollback(int txnId, String name) → bool
Rolls back to a savepoint. The transaction remains active.
inherited
setAuditEnabled({required bool enabled}) → bool
Enables or disables native audit event collection.
inherited
setLogLevel(int level) → void
Sets the native engine log level (0=Off, 1=Error, 2=Warn, 3=Info, 4=Debug, 5=Trace). A logger must be initialized by the host for output to appear.
streamCancel(int streamId) → bool
Requests cancellation of a batched stream.
inherited
streamClose(int streamId) → bool
Closes a streaming query.
inherited
streamFetch(int streamId) → StreamFetchResult
Fetches the next chunk of data from a streaming query.
inherited
streamMultiStartAsync(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, int resultEncodingWire = 0}) → int?
Async variant of streamMultiStartBatched. Status is observable via the existing streamPollAsync.
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.
inherited
streamPollAsync(int streamId) → int?
Polls async stream status.
inherited
streamStart(int connectionId, String sql, {int chunkSize = _defaultStreamChunkSize}) → int
Starts a streaming query.
inherited
streamStartAsync(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, int resultEncodingWire = 0}) → int?
Starts async batched streaming query execution.
inherited
streamStartBatched(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024, int resultEncodingWire = 0}) → int
Starts a batched streaming query.
inherited
toString() → String
A string representation of this object.
inherited
transactionBegin(int connectionId, int isolationLevel, {int savepointDialect = 0, int accessMode = 0, int lockTimeoutMs = 0}) → int
Begins a new transaction with the specified isolation level.
inherited
transactionCommit(int txnId) → bool
Commits a transaction.
inherited
transactionRollback(int txnId) → bool
Rolls back a transaction.
inherited
validateConnectionString(String connectionString) → String?
Validates connection string format without connecting.
inherited
xaCommitOnePhase(int xaId) → int
1RM optimisation: fuse prepare → commit on an active branch when this RM is the sole participant.
inherited
xaCommitPrepared(int xaId) → int
xa_commit (Phase 2) for a previously prepared branch.
inherited
xaEnd(int xaId) → int
xa_end: detach the branch from the connection. Returns 0 on success, non-zero on failure.
inherited
xaPrepare(int xaId) → int
xa_prepare: Phase 1 of 2PC.
inherited
xaRecoverCount(int connectionId) → int
xa_recover: list every XID currently in the Prepared state on the resource manager. Two-step protocol: this call queries the engine and returns the count; xaRecoverGet extracts the XID components by index.
inherited
xaRecoverGet(int index) → ({Uint8List bqual, int formatId, Uint8List gtrid})?
Extract the XID at index from the cache populated by the most recent xaRecoverCount call. Returns null when the index is out of range or the FFI fails.
inherited
xaResumePrepared({required int connectionId, required int formatId, required Uint8List gtrid, required Uint8List bqual}) → int
Resume a previously prepared XID — rebuilds an xa_id handle for crash-recovery scenarios. Returns the xa_id on success, 0 on failure.
inherited
xaRollbackActive(int xaId) → int
Roll back an Active branch (no PREPARE issued). No recovery path exists after this call.
inherited
xaRollbackPrepared(int xaId) → int
xa_rollback (Phase 2) for a previously prepared branch.
inherited
xaStart({required int connectionId, required int formatId, required Uint8List gtrid, required Uint8List bqual}) → int
xa_start: open a new XA branch on connectionId with the given XID components. Returns the xa_id on success, 0 on failure.
inherited

Operators

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