ClickHouse/clickhouse-connect v1.4.0

on GitHub

clickhouse-connect 1.4.0

This is a minor release. It adds experimental free-threading support, ships type information for downstream type checkers, and fixes bugs across the core client, the DB-API cursor, and the SQLAlchemy dialect.

Highlights

Features and improvements

• Free-threading compatibility. The Cython extension modules now declare free-threading support, so importing clickhouse-connect on a free-threaded build such as Python 3.14t no longer silently re-enables the GIL. Free-threading support remains experimental. The CI suite now runs the full test matrix on 3.14t as a non-blocking job.
• PEP 561 type information. The package now ships a py.typed marker so downstream type checkers can use its annotations. #692
• None for port and database. create_client, create_async_client, connect(), and the DB-API Connection constructor now accept None to request the driver's defaults, in addition to omitting them. The internal sentinel values are still accepted, so this is backward compatible. #801
• QueryResult.query_id now returns an empty string instead of None when the server reported no query id. This matches QuerySummary and keeps the property consistently typed as str.

Bug fixes

• QueryResult.first_item and QueryResult.first_row now return None for an empty result set instead of raising IndexError. #824
• Cursor.executemany now resets rowcount and reports the number of inserted rows after a bulk insert, and appends the insert summary to cursor.summary. Passing a generator as seq_of_parameters no longer raises TypeError. The bulk-insert optimization is skipped for non-indexable iterables and falls through to the row-by-row path as PEP 249 requires.
• A connection failure partway through reading a query result is no longer silently treated as a complete result. A mid-stream read failure now raises StreamFailureError, carrying the server-side error message when ClickHouse reported one. #802
• Client.insert_arrow and AsyncClient.insert_arrow no longer drop the transport_settings argument. It was passed positionally into the compression parameter, so transport settings were ignored. It is now forwarded correctly.
• command now raises ProgrammingError when binary parameter binds are combined with command data or external data, instead of placing binary content into the URL query string. This applies to both the sync and async clients.
• Importing clickhouse-connect no longer emits a DeprecationWarning for the array 'u' type code. This also lets projects that run with -W error import the package. #815
• The SQLAlchemy Nullable and LowCardinality DDL helpers are now functions that return a concrete ChSqlaType, so Array(LowCardinality(String)) no longer raises a spurious mypy error. Runtime behavior is unchanged. #819

Compatibility

• Client.insert, AsyncClient.insert, and raw_insert now require column_names to be a Sequence rather than a bare Iterable. A one-shot iterator such as a generator already failed at runtime because the column names are measured and iterated more than once, so the type hint now matches the real requirement.

Upgrade notes

• Building from source now requires Cython 3.1 or later.
• If you pass column_names as a generator or other one-shot iterator, switch to a Sequence such as a list or tuple. This path already failed at runtime.

Installation

pip install clickhouse-connect