Skip to content

adbc Adapter

from sqlspec.adapters.adbc import AdbcConfig, AdbcConnectionParams, AdbcDriver, AdbcDriverFeatures, AdbcExceptionHandler

Apache Arrow Database Connectivity (ADBC) adapter supporting zero-copy Arrow ingest and result streaming across PostgreSQL, SQLite, DuckDB, Snowflake, BigQuery, FlightSQL, GizmoSQL, Oracle, and IBM Db2. Inherited execution methods are documented on SyncDriverAdapterBase. See the ADBC Setup Guide for driver URI patterns and bulk Arrow ingestion.

Configuration & Parameters

AdbcConfig

Bases: NoPoolSyncConfig[AdbcConnection, 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.

AdbcConnectionParams

Bases: TypedDict

ADBC connection parameters across PyPI-installable Arrow Database Connectivity drivers.

Attributes:

Name Type Description
uri NotRequired[str]

Backend connection URI (such as postgresql://, sqlite://, duckdb://, grpc+tls://, oracle://, db2://, or quack://).
dsn NotRequired[str]

Connection string alias normalized to uri when uri is unset.
url NotRequired[str]

Connection URL alias normalized to uri when uri is unset.
connection_string NotRequired[str]

Connection string alias normalized to uri when uri is unset.
db NotRequired[str]

Database path or identifier alias normalized for file-backed and embedded ADBC drivers.
path NotRequired[str]

Filesystem database path for adbc-driver-sqlite or adbc-driver-duckdb.
driver NotRequired[str]

Short driver alias (such as 'postgresql', 'sqlite', 'duckdb', 'flightsql', 'gizmosql', 'snowflake', 'bigquery', 'oracle', 'db2', or 'quack') or shared library path.
driver_name NotRequired[str]

Explicit ADBC Python module connect path or shared library name overriding URI inference.
db_kwargs NotRequired[dict[str, Any]]

Driver-specific adbc_driver_manager.AdbcDatabase options passed to dbapi.connect.
conn_kwargs NotRequired[dict[str, Any]]

Driver-specific adbc_driver_manager.AdbcConnection options passed to dbapi.connect.
entrypoint NotRequired[str]

C symbol entrypoint name when loading a shared-object ADBC driver directly.
profile NotRequired[str]

Named credential or configuration profile forwarded to cloud ADBC drivers.
auth_type NotRequired[str]

Authentication mechanism (for example 'external' OAuth/SSO on adbc-driver-gizmosql or Snowflake auth modes).
adbc_driver_manager_entrypoint NotRequired[str]

Explicit adbc_driver_manager C initialization entrypoint symbol.
autocommit NotRequired[bool]

Enable autocommit mode on newly opened DB-API ADBC connections.
isolation_level NotRequired[str]

Transaction isolation level applied to the ADBC connection.
batch_size NotRequired[int]

Target Arrow RecordBatch row count during streaming reads and ingests.
query_timeout NotRequired[float]

Per-statement execution timeout in seconds forwarded to supporting ADBC backends.
connection_timeout NotRequired[float]

Connection establishment timeout in seconds.
ssl_mode NotRequired[str]

TLS verification mode forwarded to PostgreSQL and compatible ADBC drivers.
ssl_cert NotRequired[str]

Client TLS certificate path for mutual TLS connections.
ssl_key NotRequired[str]

Client TLS private key path paired with ssl_cert.
ssl_ca NotRequired[str]

Root CA bundle path used to verify server TLS certificates.
username NotRequired[str]

Database authentication username lifted into db_kwargs or connect() as required by the driver.
password NotRequired[str]

Database authentication password lifted into db_kwargs or connect() as required by the driver.
token NotRequired[str]

Bearer, OAuth refresh, or Quack/FlightSQL authentication token.
project_id NotRequired[str]

Google Cloud project ID mapped to adbc.bigquery.sql.project_id for adbc-driver-bigquery.
dataset_id NotRequired[str]

Default BigQuery dataset ID mapped to adbc.bigquery.sql.dataset_id.
account NotRequired[str]

Snowflake account identifier for adbc-driver-snowflake.
warehouse NotRequired[str]

Snowflake virtual warehouse name activated on connect.
database NotRequired[str]

Target catalog or database name for Snowflake, PostgreSQL, or FlightSQL backends.
schema NotRequired[str]

Default schema name for Snowflake or multi-schema ADBC backends.
role NotRequired[str]

Session role activated on connect for Snowflake or role-aware backends.
authorization_header NotRequired[str]

Explicit HTTP/gRPC Authorization header value for FlightSQL and GizmoSQL servers.
grpc_options NotRequired[dict[str, Any]]

Low-level gRPC channel options forwarded to FlightSQL, GizmoSQL, or Quack transports.
grpc_max_message_size NotRequired[int]

Maximum inbound gRPC message size in bytes for Arrow Flight transfers.
fetch_timeout NotRequired[float]

Timeout in seconds when fetching Arrow Flight result streams.
gizmosql_backend NotRequired[str]

Underlying SQL engine dialect hint when connecting through adbc-driver-gizmosql or adbc-driver-flightsql.
tls_skip_verify NotRequired[bool]

Disable server certificate verification on TLS-enabled FlightSQL or GizmoSQL endpoints.
tls_root_certs NotRequired[str]

PEM-encoded root certificate bundle for FlightSQL or GizmoSQL TLS verification.
mtls_cert_chain NotRequired[str]

PEM-encoded client certificate chain for FlightSQL or GizmoSQL mTLS.
mtls_private_key NotRequired[str]

PEM-encoded client private key paired with mtls_cert_chain.
with_cookie_middleware NotRequired[bool]

Enable stateful session cookie middleware on FlightSQL/GizmoSQL connections.
headers NotRequired[dict[str, str]]

Custom gRPC metadata headers attached to FlightSQL or GizmoSQL requests.
extra NotRequired[dict[str, Any]]

Additional driver options merged into db_kwargs.

AdbcDriverFeatures

Bases: TypedDict

ADBC driver feature flags controlling Arrow type handling, dialect probes, and DuckDB profiling.

Attributes:

Name Type Description
json_serializer NotRequired[Callable[[Any], str]]

Serializer converting dict/list parameters to JSON text (defaults to sqlspec.utils.serializers.to_json).
enable_cast_detection NotRequired[bool]

Detect explicit SQL casts such as ::jsonb or ::vector during parameter preparation (defaults to True).
enable_strict_type_coercion NotRequired[bool]

Raise an error on unsupported parameter types instead of best-effort conversion (defaults to False).
strict_type_coercion NotRequired[bool]

Alias normalized to enable_strict_type_coercion.
enable_arrow_extension_types NotRequired[bool]

Preserve PyArrow extension type metadata when materializing Arrow results (defaults to True).
arrow_extension_types NotRequired[bool]

Alias normalized to enable_arrow_extension_types.
enable_pgvector NotRequired[bool]

Probe pg_extension for vector on PostgreSQL ADBC connections (defaults to True when pgvector is installed).
enable_paradedb NotRequired[bool]

Probe pg_extension for ParadeDB pg_search on PostgreSQL ADBC connections (defaults to True).
enable_pg_textsearch NotRequired[bool]

Probe pg_extension for pg_textsearch BM25 support on PostgreSQL ADBC connections (defaults to True).
enable_lowercase_column_names NotRequired[bool]

Normalize unquoted uppercase column names to lowercase (defaults to True on Oracle and Db2 ADBC backends).
enable_events NotRequired[bool]

Enable SQLSpec table-backed event channel support.
on_connection_create NotRequired[Callable[[AdbcConnection], None]]

Callback invoked with the raw ADBC connection immediately after connect().
events_backend NotRequired[Literal['poll_queue']]

Event queue backend name ('poll_queue').
enable_statement_profiling NotRequired[bool]

Capture per-statement DuckDB JSON operator profiles on StatementEvent.profile when using DuckDB ADBC (defaults to False).

Driver & Pool

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.

AdbcExceptionHandler

Bases: BaseSyncExceptionHandler

Context manager for handling ADBC database exceptions.

Captures underlying ADBC driver errors and exposes mapped SQLSpec exceptions on pending_exception.

Extension Stores

ADBCStore

Bases: BaseSQLSpecStore['AdbcConfig']

ADBC session store using synchronous ADBC driver.

Implements server-side session storage for Litestar using ADBC (Arrow Database Connectivity) via the synchronous driver. Uses Litestar's sync_to_thread utility to provide an async interface compatible with the Store protocol.

ADBC supports multiple database backends (PostgreSQL, SQLite, DuckDB, etc.). The SQL schema is optimized for PostgreSQL by default, but can work with other backends that support TIMESTAMPTZ and BYTEA equivalents.

Provides efficient session management with
  • Sync operations wrapped for async compatibility
  • INSERT ON CONFLICT (UPSERT) for PostgreSQL
  • Automatic expiration handling with TIMESTAMPTZ
  • Efficient cleanup of expired sessions

Parameters:

Name Type Description Default
config AdbcConfig

AdbcConfig instance.

 required

AdbcADKStore

Bases: BaseSyncADKStore['AdbcConfig']

ADBC synchronous ADK store for Arrow Database Connectivity.

Implements session and event storage for Google Agent Development Kit using ADBC. ADBC provides a vendor-neutral API with Arrow-native data transfer across multiple databases (PostgreSQL, SQLite, DuckDB, etc.).

Events use the clean-break contract: id, session_id, invocation_id, timestamp, and event_data. The full ADK Event payload is stored as a single JSON blob in event_data using a dialect-appropriate column type (JSONB for PostgreSQL, JSON for DuckDB and BigQuery, VARIANT for Snowflake, TEXT for SQLite and generic fallback).

Provides
  • Session state management with JSON serialization
  • Event history tracking via single event_data blob
  • Atomic event insert + session state update
  • Timezone-aware timestamps
  • Foreign key constraints with cascade delete
  • Database-agnostic SQL (supports multiple backends)

Parameters:

Name Type Description Default
config AdbcConfig

AdbcConfig with extension_config["adk"] settings.

 required

AdbcADKMemoryStore

Bases: BaseSyncADKMemoryStore['AdbcConfig']

ADBC synchronous ADK memory store for Arrow Database Connectivity.

AdbcEventQueueStore

Bases: BaseEventQueueStore['AdbcConfig']

Event queue store for ADBC with multi-dialect support.

ADBC supports multiple database backends, so this store dynamically generates DDL appropriate for the detected dialect. Each dialect produces different column types and table structures.

Dialect detection is performed once on first access and cached for the lifetime of the store instance (database type never changes).

Supported dialects
  • PostgreSQL: JSONB columns, TIMESTAMPTZ, partial indexes
  • SQLite: TEXT columns, TIMESTAMP (default fallback)
  • DuckDB: JSON columns, TIMESTAMP
  • Oracle: CLOB columns, TIMESTAMP WITH TIME ZONE, PL/SQL existence guards
  • IBM Db2: CLOB(1M) columns, TIMESTAMP, SQLSTATE existence handlers
  • SQL Server: NVARCHAR(MAX) columns, DATETIME2, OBJECT_ID / sys.indexes guards
  • BigQuery: JSON/STRING columns, CLUSTER BY (no indexes)
  • Snowflake: VARIANT columns, no indexes supported
  • FlightSQL: Uses SQLite-compatible types (TEXT, TIMESTAMP)

Parameters:

Name Type Description Default
config AdbcConfig

AdbcConfig with extension_config["events"] settings.

 required