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.

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

supportsAsyncExecuteApi → bool

True when the loaded native library exposes async execute FFI APIs.

no setter

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

supportsDriverCapabilitiesApi → bool

True when the loaded native library exposes driver capabilities FFI API.

no setter

supportsMetadataCacheApi → bool

True when the loaded native library exposes metadata cache FFI APIs.

no setter

supportsStructuredErrorForConnection → bool

Whether the native library exposes per-connection structured error API.

no setter

Methods

asyncCancel(int requestId) → bool

Best-effort cancellation for an async request.

asyncFree(int requestId) → bool

Frees async request resources.

asyncGetResult(int requestId) → Uint8List?

Retrieves async query result payload for a completed request.

asyncPoll(int requestId) → int?

Polls async request status.

bulkInsertArray(int connectionId, String table, List<String> columns, Uint8List dataBuffer, int rowCount) → int

Performs a bulk insert operation.

bulkInsertParallel(int poolId, String table, List<String> columns, Uint8List dataBuffer, int parallelism) → int

Performs a parallel bulk insert operation through poolId.

cancelStatement(int stmtId) → bool

Cancels a prepared statement execution.

catalogColumns(int connectionId, String table) → Uint8List?

Queries the database catalog for column information.

catalogTables(int connectionId, {String catalog = '', String schema = ''}) → Uint8List?

Queries the database catalog for table information.

catalogTypeInfo(int connectionId) → Uint8List?

Queries the database catalog for data type information.

clearAllStatements() → int

Clears all prepared statements.

clearAuditEvents() → bool

Clears all in-memory native audit events.

clearStatementCache() → bool

Clears the prepared statement cache.

closeStatement(int stmtId) → bool

Closes and releases a prepared statement.

connect(String connectionString) → int

Establishes a new database connection.

connectWithTimeout(String connectionString, int timeoutMs) → int

Establishes a connection with a login timeout.

detectDriver(String connectionString) → String?

Detects the database driver from a connection string.

disconnect(int connectionId) → bool

Closes and disconnects a connection.

dispose() → void

Disposes of native resources.

execQuery(int connectionId, String sql, {int? maxBufferBytes}) → Uint8List?

Executes a SQL query and returns binary result data.

execQueryMulti(int connectionId, String sql, {int? maxBufferBytes}) → Uint8List?

Executes a SQL query that returns multiple result sets.

execQueryParams(int connectionId, String sql, Uint8List? params, {int? maxBufferBytes}) → Uint8List?

Executes a SQL query with binary parameters.

execQueryParamsTyped(int connectionId, String sql, List<ParamValue> params, {int? maxBufferBytes}) → Uint8List?

Executes a SQL query with typed parameters.

execute(int stmtId, [Uint8List? params, int timeoutOverrideMs = 0, int fetchSize = 1000, int? maxBufferBytes]) → Uint8List?

Executes a prepared statement with optional binary parameters.

executeAsyncStart(int connectionId, String sql) → int?

Starts non-blocking query execution and returns async request ID.

executeTyped(int stmtId, [List<ParamValue>? params, int timeoutOverrideMs = 0, int fetchSize = 1000, int? maxBufferBytes]) → Uint8List?

Executes a prepared statement with typed parameters.

getAuditEventsJson({int limit = 0}) → String?

Gets audit events encoded as UTF-8 JSON array.

getAuditStatusJson() → String?

Gets current audit status encoded as UTF-8 JSON object.

getCacheMetrics() → PreparedStatementMetrics?

Gets prepared statement cache metrics.

getDriverCapabilitiesJson(String connectionString) → String?

Gets driver capabilities from connection string as UTF-8 JSON object.

getError() → String

Gets the last error message from the native engine.

getMetrics() → OdbcMetrics?

Gets performance and operational metrics.

getStructuredError() → StructuredError?

Gets structured error information including SQLSTATE and native code.

getStructuredErrorForConnection(int connectionId) → StructuredError?

Gets structured error for a specific connection (per-connection isolation).

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.

metadataCacheEnable({required int maxEntries, required int ttlSeconds}) → bool

Enables or reconfigures metadata cache in native engine.

metadataCacheStatsJson() → String?

Returns metadata cache statistics as JSON payload.

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.

poolCreate(String connectionString, int maxSize) → int

Creates a new connection pool.

poolGetConnection(int poolId) → int

Gets a connection from the pool.

poolGetState(int poolId) → ({int idle, int size})?

Gets the current state of the connection pool.

poolGetStateJson(int poolId) → Map<String, dynamic>?

Gets pool state as JSON (detailed metrics for monitoring).

poolHealthCheck(int poolId) → bool

Performs a health check on the connection pool.

poolReleaseConnection(int connectionId) → bool

Releases a connection back to the pool.

poolSetSize(int poolId, int newMaxSize) → bool

Resizes the pool by recreating it with newMaxSize.

prepare(int connectionId, String sql, {int timeoutMs = 0}) → int

Prepares a SQL statement for execution.

savepointCreate(int txnId, String name) → bool

Creates a savepoint within an active transaction.

savepointRelease(int txnId, String name) → bool

Releases a savepoint. The transaction remains active.

savepointRollback(int txnId, String name) → bool

Rolls back to a savepoint. The transaction remains active.

setAuditEnabled({required bool enabled}) → bool

Enables or disables native audit event collection.

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.

streamClose(int streamId) → bool

Closes a streaming query.

streamFetch(int streamId) → StreamFetchResult

Fetches the next chunk of data from a streaming query.

streamPollAsync(int streamId) → int?

Polls async stream status.

streamStart(int connectionId, String sql, {int chunkSize = _defaultStreamChunkSize}) → int

Starts a streaming query.

streamStartAsync(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024}) → int?

Starts async batched streaming query execution.

streamStartBatched(int connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024}) → int

Starts a batched streaming query.

toString() → String

A string representation of this object.

inherited

transactionBegin(int connectionId, int isolationLevel) → int

Begins a new transaction with the specified isolation level.

transactionCommit(int txnId) → bool

Commits a transaction.

transactionRollback(int txnId) → bool

Rolls back a transaction.

validateConnectionString(String connectionString) → String?

Validates connection string format without connecting.

Operators

operator ==(Object other) → bool

The equality operator.

inherited