ClickHouse/clickhouse-connect v1.6.0

on GitHub

What's Changed

clickhouse-connect 1.6.0 adds an experimental in-process chDB backend, resolves several sync/async client parity bugs, and replaces the zstandard dependency with the standard library/a backport. Internally, the sync and async HTTP clients were unified onto a shared backend core, which is what enables the chDB backend and fixes the async issues below.

Features

• Added an experimental in-process chDB backend. get_client(interface='chdb') or a chdb:// DSN returns a standard client that runs queries against an embedded chDB engine instead of a ClickHouse server, supporting the full query, insert, streaming, and Arrow client surface. Use the path argument or a chdb:///on/disk/path DSN for a persistent database. Requires the chdb package, installable with pip install clickhouse-connect[chdb]. chDB allows one engine per process, has no async client, and does not support external data. (#872)

Bug Fixes

• AsyncClient initialization no longer overwrites user-supplied session settings with generated defaults which no matches the sync client. (#872)
• An AsyncClient created with both client certificates and an access token now sends the mutual TLS authentication headers and the Authorization: Bearer header together which now also matches the sync client. (#872)
• Dict-valued settings such as additional_table_filters no longer crash with DB::Exception: Cannot parse quoted string when passed through query()'s settings parameter. Closes #501.

Improvements

• Async clients now emit URL query parameters in the same order as the sync client on every request. (#872)
• Client creation no longer fails when the client_protocol_version capability probe errors on the sync client; it now falls back gracefully and logs at debug level, matching the async client.
• Replaced the zstandard dependency with the stdlib compression.zstd module (Python 3.14+) and backports.zstd (Python 3.10-3.13), giving a single consistent call surface across all supported Python versions. zstd compression remains fully supported on all standard Python installs. Closes #577.

Under the hood

• The sync and async HTTP clients were refactored onto a shared, internal pluggable-backend core (asyncclient.py shrank by roughly 1,200 lines of duplicated logic). This is an internal change with no public API surface, but it's the basis for the chDB backend and the sync/async parity fixes above. (#872)

Installation

pip install clickhouse-connect