ADBC Driver Manager for Python

Warnings

• gotcha The `adbc-driver-manager` package itself is primarily a low-level interface to the ADBC C API. For most application development, it is strongly recommended to use the DB-API 2.0 interface provided by specific ADBC driver packages (e.g., `adbc_driver_sqlite.dbapi.connect()`) which abstract away the manual loading of driver shared libraries.
  Fix: Prefer `import adbc_driver_FOO.dbapi` and use `adbc_driver_FOO.dbapi.connect()` for convenience and correct driver loading.
• breaking Connections (`adbc_driver_manager.AdbcConnection` or `dbapi.Connection`) and Cursors (`dbapi.Cursor`) *must* be explicitly closed to avoid resource leaks in the underlying C library. Python's garbage collection is not guaranteed to call `__del__` in a timely manner.
  Fix: Always use `with ... as` context managers for `Connection` and `Cursor` objects, or explicitly call `.close()` on them.
• gotcha The `adbc-driver-manager` package requires a separately installed ADBC driver shared library (e.g., `libadbc_driver_sqlite.so`) to function. Unlike driver-specific packages (e.g., `adbc-driver-sqlite`) which bundle and load the driver transparently, when using `adbc-driver-manager` directly, you must manage the driver's availability (e.g., via `PATH` or `LD_LIBRARY_PATH`).
  Fix: Ensure the necessary ADBC driver shared library is installed and discoverable by the driver manager, or use a driver-specific Python package.
• gotcha The DB-API 2.0 interface and functionality for working with Arrow data (e.g., `fetch_arrow_table`, `adbc_ingest`) requires the `pyarrow` library to be installed. Without `pyarrow`, such features will be unavailable or raise errors.
  Fix: Install `pyarrow` alongside `adbc-driver-manager` using `pip install adbc-driver-manager pyarrow`.
• breaking Recent Python wheels for `adbc-driver-manager` (and other Apache Arrow libraries) have increased their minimum system requirements. Specifically, `manylinux_2_28` is now required for Linux wheels (up from `manylinux2010`), and macOS 12 is the minimum supported version for macOS wheels.
  Fix: Ensure your environment meets the updated `manylinux_2_28` or macOS 12+ requirements, or pin to an older `adbc-driver-manager` version if compatibility is needed.

Install

• pip install adbc-driver-manager Core library
• pip install adbc-driver-manager pyarrow With PyArrow for DB-API features

Imports

• adbc_driver_manager

  import adbc_driver_manager

  For low-level ADBC C API bindings.
• dbapi

  import adbc_driver_sqlite.dbapi

  While `adbc_driver_manager.dbapi` exists, it's generally recommended to use the DB-API 2.0 entrypoint provided by specific driver packages (e.g., `adbc_driver_sqlite.dbapi`) for convenience, as these bundle and load the underlying driver.

Quickstart

This quickstart demonstrates connecting to a SQLite database using the recommended DB-API 2.0 interface provided by `adbc_driver_sqlite.dbapi`. It shows how to execute queries, fetch results as both Arrow Tables and standard Python rows, and perform bulk data ingestion. Ensure `adbc-driver-sqlite` and `pyarrow` are installed for this example to run. Connections and cursors should always be managed with context managers or explicitly `close()`d to prevent resource leaks.

import adbc_driver_sqlite.dbapi
import pyarrow

# Ensure the SQLite ADBC driver is installed for this example.
# pip install adbc-driver-sqlite pyarrow

try:
    # Connect to a SQLite database using the DB-API 2.0 interface
    # Use a context manager to ensure proper resource cleanup
    with adbc_driver_sqlite.dbapi.connect() as conn:
        with conn.cursor() as cur:
            # Execute a query
            cur.execute("CREATE TABLE IF NOT EXISTS test (id INTEGER, name TEXT)")
            cur.execute("INSERT INTO test (id, name) VALUES (?, ?)", (1, 'Alice'))
            cur.execute("INSERT INTO test (id, name) VALUES (?, ?)", (2, 'Bob'))

            # Fetch results as an Arrow Table (an ADBC-specific extension)
            cur.execute("SELECT id, name FROM test ORDER BY id")
            table = cur.fetch_arrow_table()
            print("Fetched Arrow Table:\n", table)

            # Fetch results via standard DB-API row-oriented interface
            cur.execute("SELECT id, name FROM test ORDER BY id")
            row = cur.fetchone()
            print(f"\nFetched one row: {row}")
            rows = cur.fetchall()
            print(f"Fetched remaining rows: {rows}")

            # Bulk ingest data
            new_data = pyarrow.table([[3, 4], ['Charlie', 'David']], names=['id', 'name'])
            cur.adbc_ingest("test", new_data)
            print(f"\nIngested {new_data.num_rows} rows.")

            cur.execute("SELECT COUNT(*) FROM test")
            count = cur.fetchone()[0]
            print(f"Total rows after ingest: {count}")

except Exception as e:
    print(f"An error occurred: {e}")