chDB as an ADBC driver

ADBC is a vendor-neutral API for moving Arrow data between an application and a database. The chDB ADBC driver is distributed through the ADBC Driver Foundry and can be loaded by any ADBC driver manager.

Results cross the boundary as Arrow record batches, with no row-by-row conversion. Applications can use the same driver from Python or from any other language with an ADBC driver manager.

Installation

Install the driver from the ADBC Driver Foundry with dbc:

dbc install chdb

The first published dbc package for chDB is version 26.7.0. To check the available versions run:

dbc search -v chdb

The installed driver can be loaded by the name chdb from an ADBC driver manager.

Linux and macOS are supported on x86-64 and arm64.

Connecting from Python

Install the Python ADBC driver manager:

pip install adbc-driver-manager pyarrow

Then load the dbc-installed chDB driver by name:

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

chDB runs one embedded engine in each process while connections are open. Keep these rules in mind:

• 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

The dbc package installs a standalone native ADBC driver. It is separate from the native library loaded by the Python chdb package.

In one Python process, do not expect a dbc-loaded ADBC connection and a regular chdb connection to share in-memory tables or engine state. For a given database path, use either the ADBC driver or the Python chdb API at one time; do not keep both open on the same on-disk path. To move data between the two APIs, close all connections on one side before opening the other, or pass data explicitly through Arrow or files.

Implemented functionality

Not yet identifies an ADBC driver capability that can be added later. Not applicable identifies a feature that does not match the current chDB or ClickHouse execution model.

Database

Connection

Statement

Bulk ingestion supports the create, append, create_append, and replace modes, into the default database or a named one.

ClickHouse SQL and type behavior

chDB uses ClickHouse SQL and its type system. The following ClickHouse semantics also apply when chDB is accessed through ADBC:

• 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.

Some Arrow types preserve their values but are read back as a different Arrow type:

Binary data is stored as String and read back as UTF-8. Payloads that are not valid UTF-8 are therefore not supported as round-trip binary values.

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

After dbc install chdb, the C driver manager can resolve the driver by name:

#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 chDB ADBC release builds run two external suites against the native driver on Linux x86-64 and arm64, and macOS x86-64 and arm64:

• 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

The support tables on this page are derived from those runs. The suites live in the chdb-core repository.