NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #2192 most downloaded on PyPI
chDB is an in-process OLAP SQL Engine powered by ClickHouse
Last release 24 days ago
11 Sep 2026
Ships fairly regularly
a new release about every 2 weeks
Nearly every release is documented
notes for 36 of 38 stable releases
10 versions withdrawn
withdrawn after publishing
4 years old
49 releases · first in 2023
One column per quarter.
Requires chdb-core>=26.7.0 ; the durable extras require chdb-core>=26.7.3 .
Requires chdb-core>=26.7.0; the durable extras require chdb-core>=26.7.3.
chdb.durable (#634, #635, #640) — a chDB database whose state lives in object storage you own. Restore is fast, a lease makes single-writer a guarantee, and an object is a folder you can move between clouds. Objects it writes are readable by the Node and Go bindings, and vice versa.
from chdb import durable as cd
ns = cd.Namespace("s3://bucket/prefix", owner="worker-1")
obj = ns.open("user-123") # lease + restore
obj.execute("INSERT INTO beliefs VALUES (...)") # local; buffered
obj.flush() # now it survives losing this machine
obj.checkpoint() # fold into a fresh base
obj.close()pip install "chdb[durable]" for S3-compatible storage (AWS, MinIO, R2, GCS via its S3 endpoint), or chdb[durable-gcs] / chdb[durable-azure] for the native ones. See docs/durable.
That was a prototype; this is the frozen V1 protocol and replaces it.
default, not mem. Existing objects keep the name in their head.local: or file:// — one URL now fits Python, Node and Go.Full Changelog: v4.3.0...v4.4.0
Release chDB with chdb-core 26.7.0 and ADBC extra support.
Release chDB with chdb-core 26.7.0 and ADBC extra support.
clickhouse-connect backend ( #593 ) — use chDB as a drop-in execution backend for clickhouse-connect: clickhouse_connect.get_client("chdb://memory") (
Requires chdb-core>=26.5.0.
clickhouse_connect.get_client("chdb://memory") (in-memory) or get_client("chdb:///path/to/data.db") (on-disk) returns a client backed by the embedded engine instead of an HTTP server. Ships as chdb.cc_backend plus a clickhouse_connect.backends entry point; install with pip install "chdb[clickhouse-connect]". End-to-end usage requires a clickhouse-connect release that includes the pluggable-backend mechanism (ClickHouse/clickhouse-connect#811).chdb.agents contract 0.2.0 (#602) — descriptors as the single source of truth, capabilities(), acall(), hardened descriptor and dispatch edges, external-session probing, allowlist scanner fixes.pyarrow<25 in the Linux arm64 DataStore test environment to work around a pyarrow 25.0.0 parquet read corruption on linux-aarch64; the pin will be removed once a fixed pyarrow release is out (#605).chdb.agents.ChDBTool (beta/experimental) — the canonical Python agent tool for chDB, and the reference implementation of a cross-language contract ( c
Requires chdb-core>=26.5.0.
chdb.agents.ChDBTool (beta/experimental) — the canonical Python agent tool for chDB, and the reference implementation of a cross-language contract (chdb/agents/CONTRACT.md). Query + introspection with engine-enforced read-only (readonly=2, keeps file()/s3()/url() usable), server-side parameter binding, result caps with an explicit truncated flag, error-to-model dispatch, optional query timeout, attach_file, an optional file allowlist, and a Python-only dataframe_query over Python(). A shared conformance fixture keeps other-language bindings in lock-step. The API is beta and may change in a minor release — pin a version if you depend on it.to_clickhouse writes an in-memory DataFrame to a ClickHouse server (same- and cross-server).pd.col() expressions; lazy metadata (.columns/.dtypes/.shape/.index resolved without materializing).output_format="DataStore" dispatch and mirrored UDF surfaces from chdb-core.All additions are backward-compatible. See the merged PRs since v4.1.9 (#561, #568, #570, #584, #591, #592, #594, #597).
feat(datastore): mirror pandas iteration on LazyGroupBy / SeriesGroupBy by @wudidapaopao in #582
Full Changelog: v4.1.8...v4.1.9
Rewrite chdb-datastore and chdb-sql skill descriptions for trigger accuracy by @ShawnChen-Sirius in #573
Full Changelog: v4.1.7...v4.1.8
Upgrade macos arm64 runner to macos-15 by @wudidapaopao in #548
Full Changelog: v4.1.6...v4.1.7
Optimize streaming DataFrame execution for 80% memory reduction by @auxten in #545
Full Changelog: v4.1.5...v4.1.6
Optimize count()/count_rows() to strip ORDER BY and use correct SQL for lazy ops by @auxten in #544
Full Changelog: v4.1.4...v4.1.5
Add chdb/ init .py to prevent broken module after upgrade by @auxten in #543
Full Changelog: v4.1.3...v4.1.4
Add Get Started on Hex section to README by @auxten in #537
Improve metadata access for pristine DataStore sources by @auxten in https://github.com/chdb-io/chdb/pull/536
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.1.1...v4.1.2
Add chdb.datastore shim and fix chdb.__version__ by @auxten in https://github.com/chdb-io/chdb/pull/535
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.1.0...v4.1.1
Upgrade dep to chdb-core v26.1.0 @wudidapaopao in https://github.com/chdb-io/chdb-core/releases/tag/v26.1.0
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.0.2...v4.1.0
Enhance documentation with architecture overview and diagramChore/readme by @auxten in https://github.com/chdb-io/chdb/pull/512
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.0.1...v4.0.2
Enhance DataStore documentation and import structure by @auxten in https://github.com/chdb-io/chdb/pull/499
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.0.0...v4.0.1
Skip ci for draft pr by @wudidapaopao in https://github.com/chdb-io/chdb/pull/422
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.7.2...v4.0.0
Fix DataFrame output with binary type by @wudidapaopao in https://github.com/chdb-io/chdb/pull/481
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.0.0b5...v4.0.0b6
Optimize performance of DataFrame string queries by @wudidapaopao in https://github.com/chdb-io/chdb/pull/468
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.0.0b4...v4.0.0b5
DataFrame output: omit timezone by default, NaN for float nulls by @wudidapaopao in https://github.com/chdb-io/chdb/pull/458
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.0.0b3...v4.0.0b4
Skip unstable network url query tests on musl Linux by @wudidapaopao in https://github.com/chdb-io/chdb/pull/438
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.0.0b2...v4.0.0b3
Fix bump version by @wudidapaopao in https://github.com/chdb-io/chdb/pull/433
Full Changelog: https://github.com/chdb-io/chdb/compare/v4.0.0b1...v4.0.0b2
Chore(ci): Build Musl arm64 by @kafka1991 in https://github.com/chdb-io/chdb/pull/421
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.7.1...v3.7.2
Feat(upgrade): update ch core to v25.8.2.29 by @kafka1991 in https://github.com/chdb-io/chdb/pull/383
connect_chdb by @kafka1991 in https://github.com/chdb-io/chdb/pull/379readthedocs's rendering issues by @kafka1991 in https://github.com/chdb-io/chdb/pull/377Full Changelog: https://github.com/chdb-io/chdb/compare/v3.6.0...v3.7.1
feat(docs): add chdb sphinx docs. by @kafka1991 in https://github.com/chdb-io/chdb/pull/375
readthedocs's rendering issues by @kafka1991 in https://github.com/chdb-io/chdb/pull/377connect_chdb by @kafka1991 in https://github.com/chdb-io/chdb/pull/379Full Changelog: https://github.com/chdb-io/chdb/compare/v3.6.0...3.7.0
Fix open session after a previous failure by @wudidapaopao in https://github.com/chdb-io/chdb/pull/359
? as placeholder to improve compatibility for DBAPI by @kafka1991 in https://github.com/chdb-io/chdb/pull/370Full Changelog: https://github.com/chdb-io/chdb/compare/v3.5.0...v3.6.0
Fix multiple query by @wudidapaopao in https://github.com/chdb-io/chdb/pull/348
# Example of Using PyArrow RecordBatchReader with `deltalake.write_deltalake`
import pyarrow as pa
from deltalake import write_deltalake
from chdb import session as chs
sess = chs.Session()
# Get streaming result in arrow format
stream_result = sess.send_query("SELECT * FROM numbers(100000)", "Arrow")
# Create RecordBatchReader with custom batch size (default rows_per_batch=1000000)
batch_reader = stream_result.record_batch(rows_per_batch=10000)
# Use RecordBatchReader with external libraries like Delta Lake
write_deltalake(
table_or_uri="./my_delta_table",
data=batch_reader,
mode="overwrite"
)
stream_result.close()
sess.close()
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.4.1...v3.5.0
Fix kafka table engine by @wudidapaopao in https://github.com/chdb-io/chdb/pull/341
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.4.0...v3.4.1
Move session temp path management from Python to C++ by @wudidapaopao in https://github.com/chdb-io/chdb/pull/337
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.3.0...v3.4.0
Fix signal loss by removing the signal handler in the ClickHouse engine by @wudidapaopao in https://github.com/chdb-io/chdb/pull/327
import chdb
import pandas as pd
dict_data = {
"a": [1, 2, 3, 4, 5, 6],
"b": ["tom", "jerry", "auxten", "tom", "jerry", "auxten"],
"dict_col": [
{'id': 1, 'tags': ['urgent', 'important'],
'metadata': {'created': '2024-01-01'}},
{'id': 2, 'tags': ['normal'],
'metadata': {'created': '2024-02-01'}},
{'id': 3, 'name': 'tom'},
{'id': 4, 'value': '100'},
{'id': 5, 'value': 101},
{'id': 6, 'value': 102},
],
}
df = pd.DataFrame(dict_data)
chdb.query("SELECT b, sum(a) FROM Python(df) GROUP BY b ORDER BY b").show()
# "auxten",9
# "jerry",7
# "tom",5
chdb.query(
"SELECT dict_col.id FROM Python(dict_data) WHERE dict_col.value='100'"
).show()
# 4
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.2.0...v3.3.0
Add connection based API example by @auxten in https://github.com/chdb-io/chdb/pull/319
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.1.2...v3.2.0
Fix connection_wrapper destructor sometimes closing other connections by @meastham in https://github.com/chdb-io/chdb/pull/312
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.1.1...v3.1.2
Fix Null, UUID and df arrow table output format by @auxten in https://github.com/chdb-io/chdb/pull/308
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.1.0...v3.1.1
Patchset post v3.0.0 by @auxten in https://github.com/chdb-io/chdb/pull/299
Full Changelog: https://github.com/chdb-io/chdb/compare/v3.0.0...v3.0.1
Skip dup call build.sh in setup.py by @auxten in https://github.com/chdb-io/chdb/pull/285
Full Changelog: https://github.com/chdb-io/chdb/compare/v2.2.0b0...v2.2.0b1
Use macOS 13 build by @auxten in https://github.com/chdb-io/chdb/pull/273
Full Changelog: https://github.com/chdb-io/chdb/compare/v2.1.0...v2.1.1
Add: support azure blob storage by @nmreadelf in https://github.com/chdb-io/chdb/pull/266
Full Changelog: https://github.com/chdb-io/chdb/compare/v2.0.3...v2.0.4
Disable ICU on macOS by @auxten in https://github.com/chdb-io/chdb/pull/221
Full Changelog: https://github.com/chdb-io/chdb/compare/v1.3.0...v1.4.1
Enable H3 functions by @auxten in https://github.com/chdb-io/chdb/pull/218
Full Changelog: https://github.com/chdb-io/chdb/compare/v1.3.0...v1.4.0
Nothing published for this version
Fix dbapi init issue and add dbapi basic tests by @Daniel-Robbins in https://github.com/chdb-io/chdb/pull/147
Full Changelog: https://github.com/chdb-io/chdb/compare/v1.0.1...v1.0.2
Enable hdfs, avro and rapidJson/simdJson by @nmreadelf in https://github.com/chdb-io/chdb/pull/123
Full Changelog: https://github.com/chdb-io/chdb/compare/v0.14.2...v0.15.0
Query stats by @auxten in https://github.com/chdb-io/chdb/pull/91
Full Changelog: https://github.com/chdb-io/chdb/compare/v0.12.0...v0.13.0
Try fix jemalloc on aarch64 by @auxten in https://github.com/chdb-io/chdb/pull/69
Full Changelog: https://github.com/chdb-io/chdb/compare/v0.11.4...v0.11.5
Restart Canceled Actions by @lmangani in https://github.com/chdb-io/chdb/pull/42
Full Changelog: https://github.com/chdb-io/chdb/compare/v0.10.2...v0.10.3
Add Python DB API 2.0 driver by @laodouya in https://github.com/chdb-io/chdb/pull/35
Full Changelog: https://github.com/chdb-io/chdb/compare/v0.8.0...v0.9.0
Fix common bug of aggregation slow by @auxten in https://github.com/chdb-io/chdb/pull/32
Full Changelog: https://github.com/chdb-io/chdb/compare/v0.7.0...v0.8.0
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →