chDB as an ADBC driver

​

Installation

dbc install chdb

dbc search -v chdb

​

Connecting from Python

pip install adbc-driver-manager pyarrow

from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(3)")
        print(cur.fetch_arrow_table())

​

Connection lifecycle

• All simultaneously open ADBC connections in a process must resolve to the same storage path.
• Multiple connections to that path are supported, including connections used concurrently from different threads. For concurrent queries, give each worker its own connection instead of running simultaneous operations on one connection.
• Closing the last connection shuts the embedded engine down. A later connection can start it again, including with a different storage path, but repeated shutdown and startup costs time and memory. Keep at least one connection open for repeated work.
• Only one operating-system process can open a given on-disk directory at a time. Give each process its own directory, or use an in-memory database.

​

Using ADBC with the Python chDB package

​

Implemented functionality

​

Database

​

Connection

​

Statement

​

ClickHouse SQL and type behavior

• Columns are not nullable unless declared Nullable(...). A typed NULL bound into a plain String column is stored as an empty string, not as NULL.
• Use ClickHouse identifier quoting; the examples use backticks.
• ClickHouse databases map to ADBC db_schema. There is no catalog layer above them, so catalog-scoped operations are not applicable.
• Decimal does not accept negative scales, and Date32 covers 1900-01-01 to 2299-12-31.
• A DateTime64 without a time zone is interpreted in the engine time zone.
• The current ClickHouse Arrow output does not represent the Time type, so it cannot be read back through ADBC.

​

Examples

​

Bulk ingestion from Arrow

import pyarrow as pa
from adbc_driver_manager import dbapi

table = pa.table({"id": [1, 2, 3], "name": ["a", "b", "c"]})

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.adbc_ingest("events", table, mode="create")
        cur.execute("SELECT count() FROM events")
        print(cur.fetchone())

​

Parameters

from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(10) WHERE number > ?", (7,))
        print(cur.fetch_arrow_table())

​

C

#include <arrow-adbc/adbc.h>
#include <arrow-adbc/adbc_driver_manager.h>

struct AdbcDatabase database = {0};
struct AdbcError error = {0};

AdbcDatabaseNew(&database, &error);
AdbcDatabaseSetOption(&database, "driver", "chdb", &error);
AdbcDatabaseSetOption(&database, "uri", "chdb://", &error);
AdbcDatabaseInit(&database, &error);

​

How the driver is verified

• the Apache Arrow ADBC conformance suite, which checks the C contract
• the ADBC Driver Foundry validation suite, which checks SQL-level behavior, type round trips, metadata, and bulk ingestion