harlequin-chdb
harlequin-chdb is a Harlequin adapter for chDB, the in-process ClickHouse
engine. It lets Harlequin run ClickHouse SQL locally without a ClickHouse
server.
Status
This is the first local implementation draft for the standalone
chdb-io/harlequin-chdb package. It targets:
- Harlequin
>=2.13,<3 - chDB
>=4.4.0 - chdb-core
>=26.7.3 - Python
>=3.10
The chdb-core>=26.7.3 floor is intentional: the adapter relies on the ADBC
read-only connection option, statement cancellation, and statement-level
bounded reads released there.
Install
pip install harlequin-chdb
For local development from this checkout:
cd harlequin-chdb
uv run --with-editable . --extra dev pytest
Run the same local checks as CI:
python -m pip install -e ".[dev]"
python -m ruff check src tests --statistics
python -m pytest -q
python -m build
Releases
Releases are published from version tags. For example, v0.1.0 builds the
wheel and source distribution, validates them with Twine, uploads them to
PyPI, and attaches the artifacts to the matching GitHub Release.
See Architecture for the adapter design and data path.
Usage
Start an in-memory chDB database:
harlequin -a chdb
Start a persistent local database:
harlequin -a chdb /path/to/chdb-data
or:
harlequin -a chdb --path /path/to/chdb-data
Pass a chDB ADBC URI directly:
harlequin -a chdb --uri 'file:/path/to/chdb-data?progress=off'
Show system databases in the catalog:
harlequin -a chdb --show-system
Use Harlequin read-only mode:
harlequin -a chdb --read-only /path/to/chdb-data
Implementation Notes
Harlequin calls connection.execute(sql) before it calls
cursor.set_limit(n). chDB ADBC bounded reads must be configured before the
statement executes. To use the native bounded-read support without breaking SQL
ordering, this adapter:
- classifies SQL with chDB's Python query classifier;
- delays read-only statements until
fetchall(), after Harlequin has supplied the limit; - applies
max_block_size,max_result_rows, andresult_overflow_mode='break'before executing a limited statement; - materializes earlier pending reads before running a later mutating/control statement, preserving statement order inside one Harlequin run.
chDB allows one storage path per Python process. Tests that need different engine modes or read-only transitions run in subprocesses.
Query results use chDB's ADBC Arrow path. The adapter returns pyarrow.Table
objects to Harlequin and avoids converting result sets through pandas or
row-wise Python objects.
License
Apache-2.0; see LICENSE.
Metadata
Release files for harlequin-chdb 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| harlequin_chdb-0.1.0.tar.gz | 17.0 kB | Without provenance | Details for harlequin_chdb-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| harlequin_chdb-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for harlequin_chdb-0.1.0-py3-none-any.whl |
Total release size: 31.7 kB
Release files / harlequin_chdb-0.1.0.tar.gz
| Download URL | harlequin_chdb-0.1.0.tar.gz |
|---|---|
| Size | 17.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ead559be50e6fee7a5ea8446d50035a17d28a11dfda6dd28cb162ce9ad749146
|
|
BLAKE2b-256 checksum How to use checksums |
ddb5a0b8729d289d6d36db843da905d8d8d65f2b6075dee0cd3a16b848f453f2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / harlequin_chdb-0.1.0-py3-none-any.whl
| Download URL | harlequin_chdb-0.1.0-py3-none-any.whl |
|---|---|
| Size | 14.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6458e5d68ee6d130d5f91ee817c8fba858df2aa4ce4c47485340d9450eed2c83
|
|
BLAKE2b-256 checksum How to use checksums |
c19acb5ec9637997817ade66c75d063abd4cd8e5ae784359840536a8189509f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for harlequin-chdb 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.