ADBC

Arrow Database Connectivity adapter providing native Arrow result handling without conversion overhead. Supports PostgreSQL, SQLite, DuckDB, BigQuery, and Snowflake with automatic driver detection and loading.

Configuration

class sqlspec.adapters.adbc.AdbcConfig

Bases: NoPoolSyncConfig[Connection, AdbcDriver]

ADBC configuration for Arrow Database Connectivity.

ADBC provides an interface for connecting to multiple database systems with Arrow-native data transfer.

Supports multiple database backends including PostgreSQL, SQLite, DuckDB, BigQuery, and Snowflake with automatic driver detection and loading.

driver_type

alias of AdbcDriver

connection_type

alias of Connection

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, observability_config=None, **kwargs)

Initialize configuration.

Parameters:

• connection_config (AdbcConnectionParams | dict[str, typing.Any] | None) – Connection configuration parameters

• connection_instance (typing.Any) – Pre-created connection instance to use instead of creating new one

• migration_config (dict[str, typing.Any] | None) – Migration configuration

• statement_config (StatementConfig | None) – Default SQL statement configuration

• driver_features (AdbcDriverFeatures | dict[str, typing.Any] | None) – Driver feature configuration (AdbcDriverFeatures)

• bind_key (str | None) – Optional unique identifier for this configuration

• extension_config (dict[str, dict[str, Any] | LitestarConfig | FastAPIConfig | StarletteConfig | FlaskConfig | ADKConfig | EventsConfig | OpenTelemetryConfig | PrometheusConfig] | None) – Extension-specific configuration (e.g., Litestar plugin settings)

• observability_config (ObservabilityConfig | None) – Adapter-level observability overrides for lifecycle hooks and observers

• **kwargs (Any) – Additional keyword arguments passed to the base configuration.

create_connection()

Create and return a new connection using the specified driver.

Return type:

Connection

Returns:

A new connection instance.

Raises:

ImproperConfigurationError – If the connection could not be established.

provide_connection(*args, **kwargs)

Provide a connection context manager.

Parameters:

• *args (Any) – Additional arguments.

• **kwargs (Any) – Additional keyword arguments.

Return type:

AdbcConnectionContext

Returns:

A connection context manager.

provide_session(*_args, statement_config=None, **_kwargs)

Provide a driver session context manager.

On first call with a PostgreSQL backend, detects pgvector/paradedb extensions and updates the dialect accordingly.

Parameters:

• *_args (Any) – Additional arguments.

• statement_config (StatementConfig | None) – Optional statement configuration override.

• **_kwargs (Any) – Additional keyword arguments.

Return type:

AdbcSessionContext

Returns:

A context manager that yields an AdbcDriver instance.

get_signature_namespace()

Get the signature namespace for AdbcConfig types.

Return type:

dict[str, typing.Any]

Returns:

Dictionary mapping type names to types.

get_event_runtime_hints()

Return polling defaults suitable for ADBC warehouses.

Return type:

EventRuntimeHints

Driver Features

class sqlspec.adapters.adbc.config.AdbcDriverFeatures

Bases: TypedDict

ADBC driver feature configuration.

Controls optional type handling and serialization behavior for the ADBC adapter. These features configure how data is converted between Python and Arrow types.

json_serializer

JSON serialization function to use. Callable that takes Any and returns str (JSON string). Default: sqlspec.utils.serializers.to_json

enable_cast_detection

Enable cast-aware parameter processing. When True, detects SQL casts (e.g., ::JSONB) and applies appropriate serialization. Currently used for PostgreSQL JSONB handling. Default: True

enable_strict_type_coercion

Enforce strict type coercion rules. When True, raises errors for unsupported type conversions. When False, attempts best-effort conversion. Default: False

strict_type_coercion

Alias for enable_strict_type_coercion.

enable_arrow_extension_types

Enable PyArrow extension type support. When True, preserves Arrow extension type metadata when reading data. When False, falls back to storage types. Default: True

arrow_extension_types

Alias for enable_arrow_extension_types.

enable_pgvector

Enable automatic pgvector extension detection. When True and the resolved dialect is PostgreSQL, queries pg_extension on the first connection to check for the vector extension. Defaults to True when the pgvector Python package is installed.

enable_paradedb

Enable ParadeDB (pg_search) extension detection. When True and the resolved dialect is PostgreSQL, queries pg_extension on the first connection to check for the pg_search extension. Defaults to True. Independent of enable_pgvector.

enable_events

Enable database event channel support. Defaults to True when extension_config[“events”] is configured. Provides pub/sub capabilities via table-backed queue (ADBC has no native pub/sub). Requires extension_config[“events”] for migration setup.

events_backend

Event channel backend selection. Only option: “table_queue” (durable table-backed queue with retries and exactly-once delivery). ADBC does not have native pub/sub, so table_queue is the only backend. Defaults to “table_queue”.

Driver

class sqlspec.adapters.adbc.AdbcDriver

Bases: SyncDriverAdapterBase

ADBC driver for Arrow Database Connectivity.

Provides database connectivity through ADBC with support for multiple database dialects, parameter style conversion, and transaction management.

__init__(connection, statement_config=None, driver_features=None)

Initialize driver adapter with connection and configuration.

Parameters:

• connection (Connection) – Database connection instance

• statement_config (StatementConfig | None) – Statement configuration for the driver

• driver_features (dict[str, typing.Any] | None) – Driver-specific features like extensions, secrets, and connection callbacks

• observability – Optional runtime handling lifecycle hooks, observers, and spans

dispatch_execute(cursor, statement)

Execute single SQL statement.

Parameters:

• cursor (Cursor) – Database cursor

• statement (SQL) – SQL statement to execute

Return type:

ExecutionResult

Returns:

Execution result with data or row count

dispatch_execute_many(cursor, statement)

Execute SQL with multiple parameter sets.

Parameters:

• cursor (Cursor) – Database cursor

• statement (SQL) – SQL statement to execute

Return type:

ExecutionResult

Returns:

Execution result with row counts

dispatch_execute_script(cursor, statement)

Execute SQL script containing multiple statements.

Parameters:

• cursor (Cursor) – Database cursor

• statement (SQL) – SQL script to execute

Return type:

ExecutionResult

Returns:

Execution result with statement counts

begin()

Begin database transaction.

Return type:

None

commit()

Commit database transaction.

Return type:

None

rollback()

Rollback database transaction.

Return type:

None

with_cursor(connection)

Create context manager for cursor.

Parameters:

connection (Connection) – Database connection

Return type:

AdbcCursor

Returns:

Cursor context manager

handle_database_exceptions()

Handle database-specific exceptions and wrap them appropriately.

Return type:

AdbcExceptionHandler

Returns:

Exception handler context manager

select_to_arrow(statement, /, *parameters, statement_config=None, return_format='table', native_only=False, batch_size=None, arrow_schema=None, **kwargs)

Execute query and return results as Apache Arrow (ADBC native path).

ADBC provides zero-copy Arrow support via cursor.fetch_arrow_table(). This is 5-10x faster than the conversion path for large datasets.

Parameters:

• statement – SQL statement, string, or QueryBuilder

• *parameters – Query parameters or filters

• statement_config – Optional statement configuration override

• return_format – “table” for pyarrow.Table (default), “batch” for RecordBatch, “batches” for list of RecordBatch, “reader” for RecordBatchReader

• native_only – Ignored for ADBC (always uses native path)

• batch_size – Batch size hint (for future streaming implementation)

• arrow_schema – Optional pyarrow.Schema for type casting

• **kwargs – Additional keyword arguments

Returns:

ArrowResult with native Arrow data

Example

>>> result = driver.select_to_arrow(
...     "SELECT * FROM users WHERE age > $1", 18
... )
>>> df = result.to_pandas()  # Fast zero-copy conversion

select_to_storage(statement, destination, /, *parameters, statement_config=None, partitioner=None, format_hint=None, telemetry=None, **kwargs)

Stream query results to storage via the Arrow fast path.

load_from_arrow(table, source, *, partitioner=None, overwrite=False, telemetry=None)

Ingest an Arrow payload directly through the ADBC cursor.

load_from_storage(table, source, *, file_format, partitioner=None, overwrite=False)

Read an artifact from storage and ingest it via ADBC.

Return type:

StorageBridgeJob

property data_dictionary: AdbcDataDictionary

Get the data dictionary for this driver.

Returns:

Data dictionary instance for metadata queries

collect_rows(cursor, fetched)

Collect ADBC rows for the direct execution path.

Return type:

tuple[list[typing.Any], list[str], int]

resolve_rowcount(cursor)

Resolve rowcount from ADBC cursor for the direct execution path.

Return type:

int

prepare_driver_parameters(parameters, statement_config, is_many=False, prepared_statement=None)

Prepare parameters with cast-aware type coercion for ADBC.

For PostgreSQL, applies cast-aware parameter processing using metadata from the compiled statement. This allows proper handling of JSONB casts and other type conversions. Respects driver_features[‘enable_cast_detection’] configuration.

Parameters:

• parameters (Any) – Parameters in any format

• statement_config (StatementConfig) – Statement configuration

• is_many (bool) – Whether this is for execute_many operation

• prepared_statement (Any | None) – Prepared statement containing the original SQL statement

Return type:

Any

Returns:

Parameters with cast-aware type coercion applied

PostgreSQL Extension Dialects

When targeting PostgreSQL, ADBC automatically detects installed extensions on the first connection and upgrades the SQL dialect accordingly:

• pgvector — If the vector extension is installed, switches to the pgvector dialect which supports distance operators (<->, <=>, <#>, <+>, <~>, <%>).

• ParadeDB — If the pg_search extension is installed (alongside vector), switches to the paradedb dialect which adds BM25 search operators (@@@, &&&, |||, ===) on top of pgvector operators.

Detection is controlled by two driver feature flags:

• enable_pgvector — Defaults to True when the pgvector Python package is installed.

• enable_paradedb — Defaults to True.

Detection runs once per config instance and caches the result. Non-PostgreSQL backends (SQLite, DuckDB, BigQuery, Snowflake) skip detection entirely.

Note

ADBC returns vector data as strings (e.g. "[0.1,0.2,0.3]"). The pgvector Python package is not required for querying vector data. It only affects the default value of enable_pgvector — when the package is installed, detection is enabled automatically. You can always set enable_pgvector=True explicitly in driver_features to enable detection without the package installed.

See the Dialects reference for full operator details.

Data Dictionary

class sqlspec.adapters.adbc.data_dictionary.AdbcDataDictionary

Bases: SyncDataDictionaryBase

ADBC multi-dialect data dictionary.

dialect: ClassVar[str] = 'generic'

Dialect identifier. Must be defined by subclasses as a class attribute.

__init__()

list_available_features()

List all features that can be checked via get_feature_flag.

Return type:

list[str]

Returns:

List of feature names this data dictionary supports

get_version(driver)

Get database version information based on detected dialect.

Return type:

VersionInfo | None

get_feature_flag(driver, feature)

Check if database supports a specific feature.

Return type:

bool

get_optimal_type(driver, type_category)

Get optimal database type for a category.

Return type:

str

get_tables(driver, schema=None)

Get tables for the current dialect.

Return type:

list[TableMetadata]

get_columns(driver, table=None, schema=None)

Get column information for a table or schema.

Return type:

list[ColumnMetadata]

get_indexes(driver, table=None, schema=None)

Get index information for a table or schema.

Return type:

list[IndexMetadata]

get_foreign_keys(driver, table=None, schema=None)

Get foreign key metadata.

Return type:

list[ForeignKeyMetadata]