ConnectionOptions class

Options for connection establishment and statement execution.

Used when calling connect to configure timeouts. loginTimeout is passed to the ODBC driver as the login/connection timeout. maxResultBufferBytes caps the size of query result buffers for this connection (default defaultMaxResultBufferBytes when null).

Constructors

ConnectionOptions({Duration? connectionTimeout, Duration? loginTimeout, Duration? queryTimeout, int? maxResultBufferBytes, int? initialResultBufferBytes, int? streamChunkSizeBytes, int? blockFetchBatchSize, int? sqlPointerCacheMaxSize, bool autoReconnectOnConnectionLost = false, int? maxReconnectAttempts, Duration? reconnectBackoff, Duration? slowQueryThreshold, bool lazyStrings = false})
const
ConnectionOptions.fromUsageProfile(OdbcUsageProfile profile)
Preset timeouts and reconnect policy for a usage profile.
factory

Properties

autoReconnectOnConnectionLost → bool
When true, the repository may attempt to reconnect and re-execute the operation on connection-lost errors. Default is false.
final
blockFetchBatchSize → int?
Preferred ODBC block-fetch row batch for buffered executeQuery* drains.
final
connectionTimeout → Duration?
Timeout for establishing the connection. When set, used as loginTimeout for the ODBC driver if loginTimeout is null.
final
effectiveMaxReconnectAttempts → int
Effective max reconnect attempts when ConnectionOptions.autoReconnectOnConnectionLost is true.
no setter
effectiveReconnectBackoff → Duration
Effective delay between reconnect attempts.
no setter
effectiveSlowQueryThreshold → Duration?
Effective slow-query threshold. Returns the explicit slowQueryThreshold when set, otherwise 80% of queryTimeout when a query timeout exists, otherwise null (no events).
no setter
hashCode → int
The hash code for this object.
no setterinherited
initialResultBufferBytes → int?
Initial size in bytes for query result buffer allocation. When null, repository runners use defaultInitialResultBufferBytes (64 KiB). Larger values (e.g. server presets at 1 MiB) reduce reallocation rounds for large result sets. Low-level FFI calls without an explicit seed still fall back to the native helper default (256 KiB).
final
lazyStrings → bool
When true, text cells in binary protocol decode paths are wrapped in LazyString instead of eagerly decoded. Opt-in for workloads that inspect only a subset of string columns.
final
loginTimeout → Duration?
Login timeout (ODBC SQL_ATTR_LOGIN_TIMEOUT). Takes precedence over connectionTimeout when both are set.
final
loginTimeoutMs → int
Effective login timeout in milliseconds: loginTimeout ?? connectionTimeout, or 0 if neither is set.
no setter
maxReconnectAttempts → int?
Maximum number of reconnect attempts when ConnectionOptions.autoReconnectOnConnectionLost is true. When null, defaultMaxReconnectAttempts is used.
final
maxResultBufferBytes → int?
Maximum size in bytes for query result buffers on this connection. When null, defaultMaxResultBufferBytes is used.
final
queryTimeout → Duration?
Timeout for individual queries. Applied when using prepared statements with a timeout (e.g. prepare with timeoutMs).
final
reconnectBackoff → Duration?
Delay between reconnect attempts. When null, defaultReconnectBackoff is used.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
slowQueryThreshold → Duration?
Threshold above which a query's wall-clock duration triggers a SlowQueryDetected event on IAdminService.events. When null, the runtime falls back to queryTimeout * 0.8 if a query timeout is set; otherwise no slow-query events are emitted.
final
sqlPointerCacheMaxSize → int?
Optional max entries for the process-local SQL UTF-8 pointer cache on the native engine constructed for this options set (default 256 when null).
final
streamChunkSizeBytes → int?
Preferred FFI stream fetch chunk size when streamQuery* callers omit chunkSize. Server presets use 1 MiB; otherwise runners fall back to 64 KiB (defaultRecommendedStreamChunkSizeBytes).
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited
validate() → String?
Returns a human-readable validation message when options are invalid.

Operators

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