sqlalchemy-adbc
Generic SQLAlchemy dialect for any Apache Arrow ADBC driver — so any tool that speaks SQLAlchemy (pandas, marimo, Superset, dbt, Polars) can read and write against Flight SQL, PostgreSQL, SQLite, Snowflake, and BigQuery through the Arrow-native wire path.
Why this exists
ADBC drivers speak Python DBAPI and return results as Arrow record batches —
zero per-row materialization, no driver-specific JDBC/ODBC install. But most
of the Python ecosystem wires into databases through SQLAlchemy, and ADBC
doesn't ship a dialect. This package is a thin translation layer: SQLAlchemy
URL → ADBC db_kwargs → DBAPI connection.
Install
pip install sqlalchemy-adbc
# With a driver extra:
pip install "sqlalchemy-adbc[flightsql]"
pip install "sqlalchemy-adbc[postgresql]"
pip install "sqlalchemy-adbc[sqlite]"
pip install "sqlalchemy-adbc[snowflake]"
pip install "sqlalchemy-adbc[bigquery]"
Quickstart
import sqlalchemy
# Flight SQL
engine = sqlalchemy.create_engine(
"flightsql+adbc://flight-sql.example.com:443?tls=true",
connect_args={"db_kwargs": {
"adbc.flight.sql.authorization_header": f"Bearer {token}",
}},
)
# SQLite
engine = sqlalchemy.create_engine("sqlite+adbc:///path/to/db.sqlite")
# PostgreSQL
engine = sqlalchemy.create_engine(
"postgresql+adbc://user:pass@host:5432/mydb"
)
# Works with pandas, Polars, marimo SQL cells, etc.
import pandas as pd
df = pd.read_sql("SELECT 1 AS n", engine)
URL forms
URLs follow SQLAlchemy's <backend>+<driver>:// convention, with adbc
as the driver. The pre-0.4 adbc+<backend>:// spelling still works but
emits a DeprecationWarning and will be removed in 1.0.
| Backend | URL |
|---|---|
| Flight SQL | flightsql+adbc://host:port?tls=true&authorization=... |
| Flight SQL | flightsql+adbc://user:TOKEN@host:port?tls=true (bearer) |
| PostgreSQL | postgresql+adbc://user:pass@host:port/database |
| SQLite | sqlite+adbc:///path/to/db or sqlite+adbc:///:memory: |
| Snowflake | snowflake+adbc://user:pass@account/db/schema?warehouse=W |
| BigQuery | bigquery+adbc:///my-project?dataset=my_dataset |
Flight SQL query-string options
| Key | Meaning |
|---|---|
tls=true |
Use grpc+tls:// instead of grpc:// |
authorization=... |
Sets the ADBC AUTHORIZATION_HEADER db_kwarg |
header.<name>=<v> |
Forwarded via ADBC's RPC_CALL_HEADER_PREFIX |
| (any other key) | Passed through as a db_kwarg verbatim |
Status
Beta. Core dialect + reflection + Alembic autogenerate work on the ADBC drivers we exercise in CI (SQLite end-to-end, PostgreSQL via service container). Not 1.0 yet — we want a few months of real-world use and at least one release without breaking changes before committing to a stable API.
Full history in CHANGELOG.md. Download tags on GitHub Releases; published wheels on PyPI.
What works
SELECT/INSERT/CREATE TABLE/DROP TABLE/ALTER TABLEfor every advertised driverMetaData.reflect(bind=engine)— full Inspector contract backed by ADBCGetObjects, including columns, PK, FK, unique constraints, indexes (native PRAGMA /pg_catalogqueries on SQLite and PG)- Alembic
autogenerate— end-to-end, reusing SQLAlchemy's native backend DDL impls via standard dialect-name lookup - URL forms for Flight SQL, PostgreSQL, SQLite, Snowflake, BigQuery with correct special-character escaping in passwords
Known limitations
- PostgreSQL range types (tstzrange, tstzmultirange, int4range, …) and hstore — not yet mapped to typed decorators; returned as raw strings. JSONB / JSON / UUID / INET / CIDR / MACADDR / MACADDR8 all round-trip through typed decorators as of 0.3.0 (#11)
- Drivers exercised in CI — SQLite fully, PostgreSQL integration-tested via service container. Snowflake / BigQuery / Flight SQL inherit the shared reflection path but have no per-driver CI (#12)
- ADBC SQLite NOT NULL reporting — fixed upstream in
adbc_driver_sqlite1.13 (Python ≥ 3.11). On older drivers every column reflects as nullable=True (#13)
Tests: 121 passing on Python 3.10–3.13, including 17 PostgreSQL integration tests against a service-container Postgres.
Development
git clone https://github.com/drls-io/sqlalchemy-adbc
cd sqlalchemy-adbc
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check src/ tests/
Releasing
Publishing is automated via PyPI trusted publishing
(OIDC, no API tokens). One-time setup on pypi.org: add a pending publisher
for project sqlalchemy-adbc, owner drls-io, repository sqlalchemy-adbc,
workflow publish.yml, environment pypi. Same for TestPyPI if you want
dry-runs.
Cutting a release:
# 1. Bump version in pyproject.toml
# 2. Commit, tag, push
git commit -am "chore: release v0.1.1"
git tag v0.1.1
git push && git push --tags
The Publish to PyPI workflow fires on the tag, builds sdist+wheel, and
uploads to pypi.org. For TestPyPI dry-runs use workflow_dispatch with
target testpypi.
License
Apache-2.0. See LICENSE.
Metadata
Release files for sqlalchemy-adbc 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sqlalchemy_adbc-0.4.0.tar.gz | 39.5 kB | With provenance | Details for sqlalchemy_adbc-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sqlalchemy_adbc-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for sqlalchemy_adbc-0.4.0-py3-none-any.whl |
Total release size: 66.9 kB
Release files / sqlalchemy_adbc-0.4.0.tar.gz
| Download URL | sqlalchemy_adbc-0.4.0.tar.gz |
|---|---|
| Size | 39.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ce0bedcdf183de3d0f0bd9fc6eadf7afb2a1cd1405b42bf64d251e32c010512f
|
|
BLAKE2b-256 checksum How to use checksums |
b22fe2f7bc9bf46bc7eb7de1dea4fb5b76090487a2a9078e80c43985544aabe1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / sqlalchemy_adbc-0.4.0-py3-none-any.whl
| Download URL | sqlalchemy_adbc-0.4.0-py3-none-any.whl |
|---|---|
| Size | 27.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
00feaea0b2a1e2dfed07804dcad2be949ee1abf7e72c25ad423f2654ffdd4c20
|
|
BLAKE2b-256 checksum How to use checksums |
6b3a610e312e18571b2585eb24e77a6d2212e59f283b96a332a8fcac3caced7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logSecurity for sqlalchemy-adbc 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sqlalchemy_adbc-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.