ADBC

Arrow Database Connectivity adapter providing native Arrow result handling. Arrow-return APIs preserve native schemas, while row-return APIs materialize Python values. 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 UUID Results

PostgreSQL-family ADBC drivers expose UUID columns as Arrow opaque binary extension values. SQLSpec decodes those values to uuid.UUID on row APIs, including scalar UUIDs, UUID[] elements, and nulls. The behavior is consistent for buffered select/select_one calls and select_stream.

Native Arrow APIs such as select_to_arrow preserve the opaque extension schema and its byte-oriented Arrow semantics. SQLite and DuckDB results are not rewritten because their ADBC schemas do not use PostgreSQL's opaque UUID extension.

Set enable_arrow_extension_types=False in driver_features to keep raw storage bytes on row APIs:

from sqlspec.adapters.adbc import AdbcConfig

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

The compatibility alias arrow_extension_types controls the same feature.

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 (Connection | None) -- 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.

on_connection_create

Callback executed when a connection is created. Receives the raw ADBC connection for low-level driver configuration.

events_backend

Event channel backend selection.

Only option

"poll_queue" (durable table-backed queue with lease-based retries and acknowledgements). ADBC does not have native pub/sub, so poll_queue is the only backend. Defaults to "poll_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

dispatch_select_stream(statement, chunk_size)

Return a native ADBC stream backed by fetch_record_batch().

Return type:

Optional[SyncRowStream[dict[str, typing.Any]]]

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__()

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

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_metadata_capabilities(driver, domains=None)

Report ADBC transport metadata capabilities without implying DDL fidelity.

Return type:

MetadataCapabilityProfile

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]

get_statistics(driver, table, schema=None, *, approximate=True)

Get native driver statistics for a table via ADBC GetStatistics.

Return type:

list[TableStatisticsMetadata]

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

Get lossy ADBC constraint shells from GetObjects.

Return type:

MetadataResult

get_ddl(driver, object_name, schema=None, *, object_type='table', include_dependencies=True, prefer_native=True, redact=True)

Fail closed because ADBC metadata is not a lossless DDL source.

Return type:

DDLResult

get_system_metadata_capabilities(driver, domains=None)

Get ADBC system metadata capability disclosures.

Return type:

tuple[SystemMetadataCapability, ...]

get_system_metadata(driver, request=None, **kwargs)

Get ADBC transport metadata through the opt-in system namespace.

Return type:

SystemMetadataResult

Native Metadata And Statistics

AdbcDataDictionary keeps SQLSpec's central dialect data-dictionary queries as the canonical fallback. It detects the database behind the ADBC connection and uses the same dialect query registry as the native adapter when ADBC metadata is unsupported, incomplete, or too broad. The standardized ADBC metadata APIs (adbc_get_objects, adbc_get_table_schema) are an optional overlay when the driver returns complete table, column, and foreign-key payloads that can be normalized to SQLSpec's public metadata types.

get_statistics is separate from the shared data dictionary surface because SQLSpec does not define a portable SQL statistics contract. It wraps adbc_get_statistics directly; unsupported drivers raise sqlspec.exceptions.OperationalError.

In the replacement data dictionary, ADBC statistics are also exposed through the opt-in system metadata namespace as transport metadata. This does not make ADBC a lossless DDL or dependency source; dialect query packs remain canonical for DDL-grade metadata.

ADBC native metadata support (driver manager 1.11.0)

Backend	Metadata behavior	Statistics behavior
PostgreSQL	Native overlay when available; central PostgreSQL SQL fallback	Native (approximate; run ANALYZE for fresh estimates)
SQLite	Native overlay when available; central SQLite SQL fallback (type names populated; nullability unreliable)	Unsupported (raises OperationalError)
DuckDB	Native overlay for single tables when schema enrichment succeeds; schema-wide column listings use central DuckDB SQL	Unsupported (raises OperationalError)
Flight SQL / GizmoSQL	Native overlay is server dependent; central dialect fallback applies when the backend dialect is mapped. DuckDB-backed GizmoSQL exposes catalogs, schemas, tables, columns, and constraints through GetObjects when the server returns a complete payload; incomplete constraint or nullability metadata falls back to SQLSpec's central dialect SQL.	Server dependent
BigQuery	Central BigQuery SQL fallback	Unverified

Precision limits:

• ADBC native name filters are SQL LIKE patterns; SQLSpec post-filters native results by exact table name, but schema filters containing _ or % may match more broadly on the server side before fallback.

• The SQLite driver reports xdbc_is_nullable as YES even for NOT NULL columns.

• Index metadata always uses SQL introspection; ADBC GetObjects has no portable index representation.

• get_statistics maps the standard ADBC statistic keys 0-6 to their canonical names (adbc.statistic.row_count and friends); driver-specific keys are reported numerically.