ADBC

Arrow Database Connectivity adapter providing native Arrow result handling without conversion overhead. SQLSpec can load the ADBC drivers for PostgreSQL, SQLite, DuckDB, BigQuery, Snowflake, Flight SQL, and GizmoSQL from one AdbcConfig surface.

Connection Configuration

ADBC configuration is driver-specific at the transport layer, so connection_config accepts both SQLSpec aliases and the keyword arguments expected by the selected ADBC driver. SQLSpec normalizes common aliases and URI schemes before calling the driver's dbapi.connect function.

Supported Backends

Backend	driver_name aliases	ADBC driver	Notes
PostgreSQL	postgres, postgresql, pg	adbc_driver_postgresql	Numeric parameters; optional pgvector and ParadeDB dialect detection.
SQLite	sqlite, sqlite3	adbc_driver_sqlite	Qmark parameters; sqlite:// URIs are normalized to file paths.
DuckDB	duckdb	adbc_driver_duckdb	Qmark and numeric parameters; duckdb:// URIs are normalized to paths.
BigQuery	bigquery, bq	adbc_driver_bigquery	Named @ parameters; project_id, dataset_id, and token are lifted into db_kwargs.
Snowflake	snowflake, sf	adbc_driver_snowflake	Qmark and numeric parameters.
Flight SQL	flightsql, grpc	adbc_driver_flightsql	Generic Flight SQL connections default to SQLite-style statement handling.
GizmoSQL	gizmosql, gizmo	adbc_driver_flightsql	Flight SQL transport with DuckDB dialect by default, or SQLite when gizmosql_backend="sqlite".

Examples

PostgreSQL:

from sqlspec.adapters.adbc import AdbcConfig

postgres = AdbcConfig(
    connection_config={
        "driver_name": "postgres",
        "uri": "postgresql://user:password@localhost:5432/app",
    }
)

SQLite:

from sqlspec.adapters.adbc import AdbcConfig

sqlite = AdbcConfig(
    connection_config={
        "driver_name": "sqlite",
        "uri": "sqlite:///tmp/app.db",
    }
)

DuckDB:

from sqlspec.adapters.adbc import AdbcConfig

duckdb = AdbcConfig(
    connection_config={
        "driver_name": "duckdb",
        "path": "/tmp/app.duckdb",
    }
)

BigQuery:

from sqlspec.adapters.adbc import AdbcConfig

bigquery = AdbcConfig(
    connection_config={
        "driver_name": "bigquery",
        "project_id": "analytics-project",
        "dataset_id": "events",
    }
)

Flight SQL:

from sqlspec.adapters.adbc import AdbcConfig

flightsql = AdbcConfig(
    connection_config={
        "driver_name": "flightsql",
        "uri": "grpc+tls://flightsql.example.com:31337",
    }
)

GizmoSQL:

from sqlspec.adapters.adbc import AdbcConfig

gizmosql = AdbcConfig(
    connection_config={
        "driver_name": "gizmosql",
        "uri": "grpc+tls://localhost:31337",
        "username": "admin",
        "password": "secret",
        "tls_skip_verify": True,
        "gizmosql_backend": "duckdb",
    }
)

GizmoSQL Notes

GizmoSQL runs over the Flight SQL ADBC driver. SQLSpec maps the common username, password, tls_skip_verify, and authorization_header shortcuts into Flight SQL db_kwargs before opening the connection. For lower-level Flight SQL options, pass db_kwargs directly:

from sqlspec.adapters.adbc import AdbcConfig

secure_gizmosql = AdbcConfig(
    connection_config={
        "driver_name": "gizmosql",
        "uri": "grpc+tls://gizmosql.example.com:31337",
        "db_kwargs": {
            "username": "admin",
            "password": "secret",
            "adbc.flight.sql.client_option.tls_root_certs": "/etc/certs/ca.pem",
            "adbc.flight.sql.client_option.mtls_cert_chain": "/etc/certs/client.pem",
            "adbc.flight.sql.client_option.mtls_private_key": "/etc/certs/client.key",
        },
    }
)

Use gizmosql_backend="sqlite" only when the target GizmoSQL server was started with SQLite as its database backend. DuckDB remains the default dialect for GizmoSQL.

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, GizmoSQL) 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.

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 | SanicConfig | FlaskConfig | ADKConfig | EventsConfig | OpenTelemetryConfig | PrometheusConfig] | None) -- Extension-specific configuration

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

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

property supports_migration_schemas: bool

Migration schema support is only available for PostgreSQL-backed ADBC drivers.

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 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

final 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, *, dialect=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.

ADBC connections operate with autocommit disabled and manage the active transaction internally, so no explicit statement is issued.

Return type:

None

commit()

Commit database transaction.

Return type:

None

rollback()

Rollback database transaction.

Return type:

None

set_migration_session_schema(schema)

Set the PostgreSQL search path for migration SQL when using ADBC PostgreSQL.

Return type:

None

set_migration_non_transactional_schema(schema)

Set the PostgreSQL search path for non-transactional migration SQL.

Return type:

None

reset_migration_session_schema()

Reset PostgreSQL search path after non-transactional migration SQL.

Return type:

None

has_schema(schema)

Return whether a PostgreSQL schema exists when using ADBC PostgreSQL.

Return type:

bool

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

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.

Return type:

StorageBridgeJob

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

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]