Skip to main content

harlequin-chdb

CI

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, and result_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)

Source distribution for harlequin-chdb 0.1.0
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)

Table of built distributions (wheels) for harlequin-chdb 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page