> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# chDB as an ADBC driver

> How to use chDB through Arrow Database Connectivity (ADBC)

export const ExperimentalBadge = () => {
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#experimental-features" className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental feature
        </a>;
};

<ExperimentalBadge />

<Warning>
  The ADBC driver is experimental. Its behavior and options may change between releases.
</Warning>

[ADBC](https://arrow.apache.org/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.

<h2 id="installation">
  Installation
</h2>

Install the driver from the ADBC Driver Foundry with [`dbc`](https://docs.columnar.tech/dbc/):

```bash theme={null}
dbc install chdb
```

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

```bash theme={null}
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.

<h2 id="connecting-from-python">
  Connecting from Python
</h2>

Install the Python ADBC driver manager:

```bash theme={null}
pip install adbc-driver-manager pyarrow
```

Then load the `dbc`-installed chDB driver by name:

```python theme={null}
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())
```

| `uri`                   | Database                                      |
| ----------------------- | --------------------------------------------- |
| `chdb://`               | In-memory                                     |
| `chdb:///absolute/path` | On disk, persisted in the specified directory |

<h2 id="connection-lifecycle">
  Connection lifecycle
</h2>

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.

<h3 id="using-python-chdb-package">
  Using ADBC with the Python chDB package
</h3>

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.

<h2 id="implemented-functionality">
  Implemented functionality
</h2>

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

<h3 id="database">
  Database
</h3>

| Function                               | Status    | Notes                                      |
| -------------------------------------- | --------- | ------------------------------------------ |
| `AdbcDatabaseNew` / `Init` / `Release` | Supported |                                            |
| `AdbcDatabaseSetOption`                | Supported | `uri`, `path`, and `chdb.*` engine options |

<h3 id="connection">
  Connection
</h3>

| Function                                 | Status         | Notes                                                                                        |
| ---------------------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `AdbcConnectionNew` / `Init` / `Release` | Supported      |                                                                                              |
| `AdbcConnectionGetInfo`                  | Supported      |                                                                                              |
| `AdbcConnectionGetObjects`               | Supported      | All depths                                                                                   |
| `AdbcConnectionGetTableSchema`           | Supported      |                                                                                              |
| `AdbcConnectionGetTableTypes`            | Supported      |                                                                                              |
| `AdbcConnectionGetOption`                | Supported      | Includes the current `db_schema`                                                             |
| `AdbcConnectionSetOption`                | Partial        | Autocommit must remain enabled; changing `db_schema` is not exposed                          |
| `AdbcConnectionCommit` / `Rollback`      | Not applicable | ClickHouse statements are autocommit; there is no classic transaction to commit or roll back |
| `AdbcConnectionGetStatistics`            | Not yet        | Table statistics are not exposed through the driver                                          |
| `AdbcConnectionReadPartition`            | Not applicable | The driver does not produce distributed result partitions                                    |
| `AdbcConnectionCancel`                   | Not yet        | chDB query cancellation is not yet exposed through ADBC                                      |

<h3 id="statement">
  Statement
</h3>

| Function                           | Status         | Notes                                                    |
| ---------------------------------- | -------------- | -------------------------------------------------------- |
| `AdbcStatementNew` / `Release`     | Supported      |                                                          |
| `AdbcStatementSetSqlQuery`         | Supported      | ClickHouse SQL                                           |
| `AdbcStatementPrepare`             | Supported      |                                                          |
| `AdbcStatementBind` / `BindStream` | Supported      | Positional `?` parameters                                |
| `AdbcStatementGetParameterSchema`  | Supported      |                                                          |
| `AdbcStatementExecuteQuery`        | Supported      | Streams Arrow record batches                             |
| `AdbcStatementSetOption`           | Supported      | Bulk ingestion, see below                                |
| `AdbcStatementExecuteSchema`       | Not yet        | The result schema is currently available after execution |
| `AdbcStatementExecutePartitions`   | Not applicable | Results are returned as an in-process Arrow stream       |
| `AdbcStatementSetSubstraitPlan`    | Not applicable | chDB accepts ClickHouse SQL, not Substrait plans         |
| `AdbcStatementCancel`              | Not yet        | chDB query cancellation is not yet exposed through ADBC  |

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

<h2 id="clickhouse-sql-and-type-behavior">
  ClickHouse SQL and type behavior
</h2>

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:

| Arrow type                                         | Stored as        | Read back as        |
| -------------------------------------------------- | ---------------- | ------------------- |
| `binary`, `large_binary`, `binary_view`            | `String`         | `string`            |
| `fixed_size_binary` (bulk ingest into a new table) | `FixedString(n)` | `fixed_size_binary` |
| `large_string`, `string_view`                      | `String`         | `string`            |
| `float16`                                          | `Float32`        | `float`             |
| `time32` / `time64` / `timestamp`                  | `DateTime64(n)`  | `timestamp`         |

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.

<h2 id="examples">
  Examples
</h2>

<h3 id="bulk-ingestion">
  Bulk ingestion from Arrow
</h3>

```python theme={null}
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())
```

<h3 id="parameters">
  Parameters
</h3>

```python theme={null}
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())
```

<h3 id="c-example">
  C
</h3>

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

```c theme={null}
#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);
```

<h2 id="verification">
  How the driver is verified
</h2>

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](https://github.com/chdb-io/chdb-core/tree/main/programs/local/adbc/validation).