clickhouse-connect v1.12.0

Highlights

Features

• ping() on the sync and async clients accepts an optional timeout in seconds (default 3). Closes #192.
• New get_client(dedicated_pool=True) gives a synchronous HTTP client its own connection pool. Closing a client-owned pool now closes idle connections immediately. Closes #1121.

Performance

• Faster Array column reads with the C extensions in all query methods. Related to #1008.
• Faster Cython decoding of Date and Date32 columns.
• Faster query_df reads of Map, nullable integer, nullable date, and timezone-aware nullable datetime columns with the Python codec.
• AsyncClient.query_rows_stream reads each block in one executor call instead of one per row, so it is much faster.
• Faster client creation with non-UTC IANA server timezones. Closes #1120.
• Eligible SQLAlchemy Core and ORM SELECTs skip the extra LIMIT 0 metadata query for empty results. Closes #1108 and #1134.

Bug Fixes

• Correct Date32 decoding before 1601 and in leap centuries such as 1600 and 2400.
• Nullable(Tuple(...)) and Nullable(Point) now read and insert correctly with the Python codec, including NULLs. Closes #1102 and #1104.
• pandas.Timestamp keeps nanoseconds in DateTime64(7..9) binds and inserts. Tuple, Nested, Map, and Variant parameters keep DateTime64 precision. Related to #429.
• Datetime parameters whose names end in _64 no longer fail with KeyError in pyformat queries. Closes #1131.
• Large queries are no longer form-encoded automatically, which avoids Field value too long errors. Closes #1105.
• NumPy and pandas reads: LIMIT 0 queries return empty results, object-column rows keep the correct shape, and numeric LowCardinality columns return every row.
• query_df with use_none=False works on Nullable(Date) and Nullable(Date32).
• Async connection drops raise OperationalError or StreamFailureError instead of leaking aiohttp errors. Mid-stream drops on both clients report StreamFailureError and keep the original cause.
• AsyncClient.query(context=...) applies per-call arguments, and query(context=...) runs a stored command statement.
• Context tz_mode is preserved across all query methods.
• Enum names with backslashes or control characters parse and insert correctly. See #1117.
• Decimal256(S) resolves to precision 76.
• Fixes to timezone file handling, Tuple serialization error reporting, Nullable(SimpleAggregateFunction) NULL inserts, and a C buffer crash on zero-length first reads.

Other

• AsyncClient.raw_insert now types insert_block as an async iterable of bytes. Runtime behavior is unchanged.

Note for Python 3.14+

lz4 is no longer installed by default on Python 3.14 and later. In that case compress=True compresses inserts with zstd from the standard library. To keep using compress="lz4",install clickhouse-connect[lz4]. Nothing changes below 3.14.

Installation

pip install --upgrade clickhouse-connect

See the CHANGELOG for full details.