IOdbcService class abstract

Interface for ODBC service operations.

Allows decorators and alternative implementations to be used interchangeably via dependency injection.

Aggregates five narrower sub-interfaces:

• IQueryService — query / stream operations.
• ITransactionService — local 2PC + XA lifecycle.
• IPoolService — connection pool management.
• IAdminService — initialization, metrics, capabilities.
• IDialectService — dialect SQL builders (UPSERT / RETURNING / session).

New consumers are encouraged to depend on the narrowest sub-interface they need (Interface Segregation Principle). Existing code that types against IOdbcService keeps working unchanged because every member stays declared at the aggregate level.

Implemented types

• IQueryService
• ITransactionService
• IPoolService
• IAdminService
• IDialectService

Implementers

• OdbcService
• TelemetryOdbcServiceDecorator

Available extensions

• IOdbcServiceTypedParamExtensions
• IQueryServiceConnectionOverloads
• IQueryServiceTypedParamExtensions
• ITransactionServiceConnectionOverloads

Constructors

IOdbcService()

Properties

events → Stream<OdbcEvent>

Broadcast stream of connection-lifecycle events emitted by the runtime (connection lost, worker recovered, pool resized, etc.).

no setter, override

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

supportsDialectApi → bool

True when the loaded native library exports the dialect capability FFIs.

no setter, inherited

Methods

appendReturningClause({required String connectionString, required String sql, required DmlVerb verb, required List<String> columns}) → String?

Append a RETURNING/OUTPUT clause to sql.

inherited

asyncCancel(int requestId) → Future<Result<void>>

asyncFree(int requestId) → Future<Result<void>>

asyncGetResult(int requestId, {int? maxBufferBytes}) → Future<Result<QueryResult>>

asyncPoll(int requestId) → Future<Result<int>>

beginTransaction(String connectionId, {IsolationLevel? isolationLevel, SavepointDialect? savepointDialect, TransactionAccessMode? accessMode, Duration? lockTimeout}) → Future<Result<int>>

override

beginTransactionFor(Connection conn, {IsolationLevel? isolationLevel, SavepointDialect? savepointDialect, TransactionAccessMode? accessMode, Duration? lockTimeout}) → Future<Result<int>>

Available on ITransactionService, provided by the ITransactionServiceConnectionOverloads extension

beginTransaction overload that accepts a Connection.

buildUpsertSql({required String connectionString, required String table, required List<String> columns, required List<String> conflictColumns, List<String>? updateColumns}) → String?

Build an UPSERT statement for the dialect implied by connectionString.

inherited

bulkInsert(String connectionId, String table, List<String> columns, List<int> dataBuffer, int rowCount) → Future<Result<int>>

bulkInsertParallel(int poolId, String table, List<String> columns, List<int> dataBuffer, int rowCount, {int parallelism = 0}) → Future<Result<int>>

cancelStatement(String connectionId, int stmtId) → Future<Result<void>>

Requests cancellation of an in-flight prepared statement.

cancelStream(int streamId) → Future<Result<void>>

catalogColumns(String connectionId, String table) → Future<Result<QueryResult>>

catalogForeignKeys(String connectionId, String table) → Future<Result<QueryResult>>

catalogIndexes(String connectionId, String table) → Future<Result<QueryResult>>

catalogPrimaryKeys(String connectionId, String table) → Future<Result<QueryResult>>

catalogTables({required String connectionId, String catalog = '', String schema = ''}) → Future<Result<QueryResult>>

catalogTypeInfo(String connectionId) → Future<Result<QueryResult>>

clearAllStatements() → Future<Result<void>>

clearAuditEvents() → Future<Result<void>>

clearMetadataCache() → Future<Result<void>>

clearStatementCache() → Future<Result<void>>

closeStatement(String connectionId, int stmtId) → Future<Result<void>>

commitTransaction(String connectionId, int txnId) → Future<Result<void>>

override

connect(String connectionString, {ConnectionOptions? options}) → Future<Result<Connection>>

override

createSavepoint(String connectionId, int txnId, String name) → Future<Result<void>>

detectDriver(String connectionString) → Future<String?>

disconnect(String connectionId) → Future<Result<void>>

override

dispose() → void

executeAsyncStart(String connectionId, String sql) → Future<Result<int>>

executePreparedNamed(String connectionId, int stmtId, Map<String, Object?> namedParams, StatementOptions? options) → Future<Result<QueryResult>>

executePreparedParamValues(String connectionId, int stmtId, List<ParamValue>? params, StatementOptions? options) → Future<Result<QueryResult>>

executePreparedParamValuesFromObjects(String connectionId, int stmtId, List<Object?>? params, StatementOptions? options) → Future<Result<QueryResult>>

Available on IOdbcService, provided by the IOdbcServiceTypedParamExtensions extension

Prepared positional execute with automatic ParamValue conversion.

executeQuery(String sql, {String? connectionId}) → Future<Result<QueryResult>>

Convenience query after connect() using the active connection id.

override

executeQueryColumnarFromObjects(String connectionId, String sql, {List<Object?>? params}) → Future<Result<TypedColumnarResult>>

Available on IQueryService, provided by the IQueryServiceTypedParamExtensions extension

Columnar execute with automatic ParamValue conversion.

executeQueryColumnarParamValues(String connectionId, String sql, {List<ParamValue>? params}) → Future<Result<TypedColumnarResult>>

Column-major opt-in variant of executeQueryParamValues.

override

executeQueryColumnarParamValuesFor(Connection conn, String sql, {List<ParamValue>? params}) → Future<Result<TypedColumnarResult>>

Available on IQueryService, provided by the IQueryServiceConnectionOverloads extension

executeQueryColumnarParamValues overload that accepts a Connection.

executeQueryDirectedParams(String connectionId, String sql, List<DirectedParam> params) → Future<Result<QueryResult>>

Like positional executeQueryParams for OUT / INOUT (DRT1 on the wire).

override

executeQueryFor(Connection conn, String sql) → Future<Result<QueryResult>>

Available on IQueryService, provided by the IQueryServiceConnectionOverloads extension

executeQuery overload that accepts a Connection.

executeQueryMulti(String connectionId, String sql) → Future<Result<QueryResult>>

executeQueryMultiFull(String connectionId, String sql) → Future<Result<QueryResultMulti>>

executeQueryMultiParamValues(String connectionId, String sql, List<ParamValue> params) → Future<Result<QueryResultMulti>>

Executes a parameterised batch SQL and returns all multi-result items.

executeQueryMultiParamValuesFromObjects(String connectionId, String sql, List<Object?> params) → Future<Result<QueryResultMulti>>

Available on IOdbcService, provided by the IOdbcServiceTypedParamExtensions extension

Multi-result positional execute with automatic ParamValue conversion.

executeQueryNamed(String connectionId, String sql, Map<String, Object?> namedParams) → Future<Result<QueryResult>>

override

executeQueryNamedFor(Connection conn, String sql, Map<String, Object?> namedParams) → Future<Result<QueryResult>>

Available on IQueryService, provided by the IQueryServiceConnectionOverloads extension

executeQueryNamed overload that accepts a Connection.

executeQueryParamValues(String connectionId, String sql, List<ParamValue> params, {ResultEncoding? resultEncoding}) → Future<Result<QueryResult>>

Typed positional parameters via ParamValue wire tags.

override

executeQueryParamValuesFor(Connection conn, String sql, List<ParamValue> params, {ResultEncoding? resultEncoding}) → Future<Result<QueryResult>>

Available on IQueryService, provided by the IQueryServiceConnectionOverloads extension

executeQueryParamValues overload that accepts a Connection.

executeQueryParamValuesFromObjects(String connectionId, String sql, List<Object?> params, {ResultEncoding? resultEncoding}) → Future<Result<QueryResult>>

Available on IQueryService, provided by the IQueryServiceTypedParamExtensions extension

Positional execute with automatic ParamValue conversion.

getAuditEvents({int limit = 0}) → Future<Result<List<Map<String, Object?>>>>

getAuditStatus() → Future<Result<Map<String, Object?>>>

getConnectionDbmsInfo(String connectionId) → Future<Result<DbmsInfo>>

getDriverCapabilities(String connectionString) → Future<Result<Map<String, Object?>>>

override

getMetrics() → Future<Result<OdbcMetrics>>

override

getPreparedStatementsMetrics() → Future<Result<PreparedStatementMetrics>>

getSessionInitSql({required String connectionString, SessionOptions? options}) → List<String>?

Post-connect session init statements for the dialect.

inherited

getVersion() → Future<Result<Map<String, String>>>

getWorkerPoolStats() → Future<AsyncWorkerPoolStats?>

Returns Dart-side worker-pool statistics when the underlying connection runs in async mode (P95 latency, fallbacks to blocking, queue depth, etc.). Returns null in sync mode where no worker pool exists.

override

initialize() → Future<Result<void>>

override

isInitialized() → bool

metadataCacheEnable({required int maxEntries, required int ttlSeconds}) → Future<Result<void>>

metadataCacheStats() → Future<Result<Map<String, Object?>>>

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

poolClose(int poolId) → Future<Result<void>>

override

poolCreate(String connectionString, int maxSize, {PoolOptions? options, ConnectionOptions? connectionOptions}) → Future<Result<int>>

override

poolGetConnection(int poolId, {ConnectionOptions? options}) → Future<Result<Connection>>

override

poolGetState(int poolId) → Future<Result<PoolState>>

poolGetStateDetailed(int poolId) → Future<Result<Map<String, Object?>>>

poolHealthCheck(int poolId) → Future<Result<bool>>

override

poolReleaseConnection(String connectionId) → Future<Result<void>>

override

poolSetSize(int poolId, int newMaxSize) → Future<Result<void>>

override

prepare(String connectionId, String sql, {int timeoutMs = 0}) → Future<Result<int>>

prepareNamed(String connectionId, String sql, {int timeoutMs = 0}) → Future<Result<int>>

releaseSavepoint(String connectionId, int txnId, String name) → Future<Result<void>>

rollbackToSavepoint(String connectionId, int txnId, String name) → Future<Result<void>>

rollbackTransaction(String connectionId, int txnId) → Future<Result<void>>

override

runInTransaction<T extends Object>(String connectionId, Future<Result<T>> action(int txnId), {IsolationLevel? isolationLevel, SavepointDialect? savepointDialect, TransactionAccessMode? accessMode, Duration? lockTimeout}) → Future<Result<T>>

Runs action inside a transaction with automatic commit on success and rollback on any failure (returned Failure or thrown exception).

override

runInTransactionFor<T extends Object>(Connection conn, Future<Result<T>> action(int txnId), {IsolationLevel? isolationLevel, SavepointDialect? savepointDialect, TransactionAccessMode? accessMode, Duration? lockTimeout}) → Future<Result<T>>

Available on ITransactionService, provided by the ITransactionServiceConnectionOverloads extension

runInTransaction overload that accepts a Connection.

runInXaTransaction<T extends Object>(String connectionId, Xid xid, Future<Result<T>> action(XaTransactionHandle xa), {bool onePhase = false}) → Future<Result<T>>

Runs action inside a distributed XA / 2PC branch on connectionId.

setAuditEnabled({required bool enabled}) → Future<Result<void>>

setLogLevel(int level) → Future<Result<void>>

streamPollAsync(int streamId) → Future<Result<int>>

streamQuery(String connectionId, String sql) → Stream<Result<QueryResult>>

override

streamQueryColumnar(String connectionId, String sql) → Stream<Result<TypedColumnarResult>>

Batched streaming with columnar v2 wire when supported (odbc_stream_start_batched_options). See IQueryService.streamQueryColumnar for semantics and fallbacks.

override

streamQueryColumnarFor(Connection conn, String sql) → Stream<Result<TypedColumnarResult>>

Available on IQueryService, provided by the IQueryServiceConnectionOverloads extension

streamQueryColumnar overload that accepts a Connection.

streamQueryFor(Connection conn, String sql) → Stream<Result<QueryResult>>

Available on IQueryService, provided by the IQueryServiceConnectionOverloads extension

streamQuery overload that accepts a Connection.

streamQueryMulti(String connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024}) → Stream<Result<QueryResultMultiItem>>

Streams a multi-result batch one item at a time. New in v3.3.0 (M8).

override

streamQueryNamed(String connectionId, String sql, Map<String, Object?> namedParams) → Stream<Result<QueryResult>>

Executes a named-parameter query and returns results as a stream.

override

streamQueryNamedFor(Connection conn, String sql, Map<String, Object?> namedParams) → Stream<Result<QueryResult>>

Available on IQueryService, provided by the IQueryServiceConnectionOverloads extension

streamQueryNamed overload that accepts a Connection.

streamStartAsync(String connectionId, String sql, {int fetchSize = 1000, int chunkSize = 64 * 1024}) → Future<Result<int>>

toString() → String

A string representation of this object.

inherited

validateConnectionString(String connectionString) → Future<Result<void>>

override

xaRecover(String connectionId) → Future<Result<List<Xid>>>

List prepared XIDs on the resource manager for crash recovery.

xaResumePrepared(String connectionId, Xid xid) → Future<Result<XaTransactionHandle>>

Resume a prepared XID as an XaTransactionHandle in prepared state.

Operators

operator ==(Object other) → bool

The equality operator.

inherited