ADBC PostgreSQL Driver
raw JSON → 1.11.0 verified Sat Apr 25 auth: no python
The `adbc-driver-postgresql` package provides Python bindings for a libpq-based ADBC (Arrow Database Connectivity) driver for PostgreSQL. It offers a DBAPI 2.0-compatible interface, enabling high-performance data access to PostgreSQL databases by leveraging Apache Arrow for columnar data interchange. The library is currently active, with version 1.11.0, and typically releases in conjunction with the broader Apache Arrow ADBC project.
pip install adbc-driver-postgresql Common errors
error ModuleNotFoundError: No module named 'adbc_driver_postgresql' ↓
cause The 'adbc_driver_postgresql' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install adbc-driver-postgresql'.
error ImportError: cannot import name 'dbapi' from 'adbc_driver_postgresql' ↓
cause The 'dbapi' module is not available in the 'adbc_driver_postgresql' package, possibly due to an incorrect installation or version mismatch.
fix
Ensure that the 'adbc-driver-postgresql' package is correctly installed and up to date: 'pip install --upgrade adbc-driver-postgresql'.
error AttributeError: module 'adbc_driver_postgresql' has no attribute 'connect' ↓
cause The 'connect' function is not directly available in the 'adbc_driver_postgresql' module; it resides in the 'dbapi' submodule.
fix
Import the 'dbapi' submodule to access the 'connect' function: 'from adbc_driver_postgresql.dbapi import connect'.
error OperationalError: could not connect to server: Connection refused ↓
cause The PostgreSQL server is not running, or the connection parameters (host, port) are incorrect.
fix
Verify that the PostgreSQL server is running and that the connection parameters are correct.
error TypeError: 'NoneType' object is not subscriptable ↓
cause A function is returning 'None' instead of an expected object, possibly due to a failed database connection.
fix
Check the database connection and ensure that it is successful before proceeding with operations.
Warnings
deprecated The `ADBC:postgresql:typname` metadata key, previously attached to schema fields for unknown columns, has been deprecated in favor of the `Opaque` canonical extension type. Users should not rely on this key's continued existence. ↓
fix Migrate to using the `Opaque` extension type metadata for differentiating binary column intent.
gotcha The PostgreSQL driver uses `COPY` for optimal performance in query execution by default. However, this optimization is not supported for all queries (e.g., `SHOW` queries). Such queries may fail or produce unexpected results. ↓
fix For queries incompatible with `COPY`, disable the optimization by setting the statement option `adbc.postgresql.use_copy` to `False` (or `0`).
gotcha The PostgreSQL ADBC driver's support for prepared statements with parameters is currently limited to queries that *do not* return result sets (e.g., `INSERT`, `UPDATE`). This is due to the driver's reliance on the `COPY` protocol for performance, which is not compatible with parameterized `SELECT` statements. ↓
fix Avoid using prepared statements with parameters for `SELECT` queries that are expected to return results. Construct queries with string formatting (carefully, to avoid SQL injection) or use alternative fetching mechanisms for such cases.
gotcha There are known limitations and specific behaviors in type mapping between PostgreSQL and Arrow/Python types. Notably, PostgreSQL `NUMERIC` types are read as their string representation, and time zone information in `timestamp` values is ignored during binding. ↓
fix Be aware of type conversions and handle them explicitly in your application code. For `NUMERIC`, parse the string to the desired numeric type. For timestamps, ensure time zone handling is managed before binding or after fetching, if critical.
gotcha Failure to explicitly close connections and cursors can lead to resource leaks (e.g., database connections remaining open indefinitely). While the Python driver manager attempts to close unclosed cursors when a connection is closed, explicit management is best practice. ↓
fix Always use `with` statements for `connect()` and `cursor()` calls to ensure proper resource management and automatic closure. For manual connections, ensure `conn.close()` is called in a `finally` block.
Install
mamba install adbc-driver-postgresql # Note: This Python package requires an underlying C/C++ ADBC PostgreSQL driver (libadbc_driver_postgresql.so/.dll/.dylib) to be available in your system's library path or specified via ADBC_POSTGRESQL_LIBRARY environment variable. Standard pip/conda installations often handle this for common platforms.
export ADBC_POSTGRESQL_LIBRARY=/path/to/libadbc_driver_postgresql.so Install compatibility last tested: 2026-04-25
runtime status import time mem disk
3.10-alpine — — —
3.10-slim 0.03s 2.0MB 46M
3.11-alpine — — —
3.11-slim 0.06s 2.2MB 48M
3.12-alpine — — —
3.12-slim 0.06s 1.8MB 40M
3.13-alpine — — —
3.13-slim 0.04s 1.6MB 40M
3.9-alpine — — —
3.9-slim 0.04s 1.9MB 37M
Imports
- connect
import adbc_driver_postgresql.dbapi conn = adbc_driver_postgresql.dbapi.connect(...)
Quickstart
import os
import adbc_driver_postgresql.dbapi
# Configure your PostgreSQL connection URI.
# For example, using a local Dockerized PostgreSQL with default credentials:
# docker run -it --rm -e POSTGRES_PASSWORD=password -e POSTGRES_DB=testdb -p 5432:5432 postgres:latest
# export ADBC_POSTGRESQL_TEST_URI="postgresql://postgres:password@localhost:5432/testdb"
uri = os.environ.get("ADBC_POSTGRESQL_TEST_URI", "postgresql://user:password@localhost:5432/mydb")
try:
with adbc_driver_postgresql.dbapi.connect(uri) as conn:
with conn.cursor() as cur:
# DDL operations
cur.execute("DROP TABLE IF EXISTS example_adbc;")
cur.execute("CREATE TABLE example_adbc (id INTEGER, name VARCHAR(50));")
# DML operations with bind parameters
cur.executemany("INSERT INTO example_adbc VALUES (?, ?);", [(1, 'Alice'), (2, 'Bob')])
conn.commit() # Commit changes for DML
# Query data and fetch as an Arrow Table (requires pyarrow)
cur.execute("SELECT id, name FROM example_adbc WHERE id > 0;")
result_table = cur.fetch_arrow_table()
print("Fetched Arrow Table:")
print(result_table)
# Query data and fetch a single row
cur.execute("SELECT id, name FROM example_adbc WHERE id = 1;")
first_row = cur.fetchone()
print(f"\nFetched one row: {first_row}")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure your PostgreSQL database is running and ADBC_POSTGRESQL_TEST_URI is set correctly.")