ClickHouse/clickhouse-connect v1.0.0

on GitHub

clickhouse-connect 1.0.0

The first stable release of clickhouse-connect. 1.0.0 is identical in code to 1.0.0rc3. No changes have been merged since that tag.

Installation:

pip install clickhouse-connect

Upgrading from 0.x

The 1.0 release includes breaking changes accumulated across the rc1/rc2/rc3 cycle. If you are upgrading from a 0.15.x or earlier release, please read MIGRATION.md for a guide to the changes and their replacements.

At a glance, the breaking changes are:

• Python 3.10 minimum (3.9 dropped. 0.15.x is the last series supporting 3.9)
• pandas 2.0 minimum (1.x dropped)
• pytz dependency replaced with stdlib zoneinfo (install the tzdata extra on slim Linux containers)
• utc_tz_aware -> tz_mode ("naive_utc" / "aware" / "schema")
• apply_server_timezone -> tz_source ("auto" / "server" / "local")
• preserve_pandas_datetime_resolution setting removed: DateTime/DateTime64 now return their natural numpy resolution
• Executor-based async client removed: use clickhouse_connect.get_async_client() (native aiohttp, installed via the async extra)

Highlights

Performance

1.0 includes substantial Cython read- and write-path improvements over the 0.15.x series:

• Order-of-magnitude faster DateTime/DateTime64 reads for naive UTC and UTC-equivalent timezones, via epoch arithmetic and the CPython datetime C API.
• Order-of-magnitude faster fixed-width numeric inserts from numpy arrays, with significantly lower peak memory, 1-D C-contiguous arrays of matching dtype are now copied directly via memcpy.
• Significantly faster Map reads and writes, with reads avoiding the intermediate pair-tuple materialization.
• Significantly faster Decimal and BigDecimal reads, the decode path now builds values directly from the integer column via Decimal.scaleb instead of constructing intermediate strings per row.

Bug fixes

Notable fixes that shipped during the RC cycle:

• Fix intermittent Code: 62. Empty query. (SYNTAX_ERROR) on inserts when a pooled keep-alive connection is reset between attempts. (#731)
• Async client: retry once when aiohttp raises bare ServerDisconnectedError("Server disconnected") on a pooled keep-alive connection idle-closed by the server.
• Fix Dynamic/JSON column reads when a path's inferred type sorts alphabetically after "SharedVariant". (#712)
• Fix async streaming race condition that caused unhandled InvalidStateError on early stream termination.
• SQLAlchemy: wrap raw SQL strings in text() in Inspector.get_schema_names() / get_table_names() so they work on SQLAlchemy 2.x.
• SQLAlchemy: Bool type now accepts and forwards **kwargs, fixing ORM model use and Table.to_metadata(). (#705)
• SQLAlchemy: CreateDatabase with engine="Replicated" now emits valid DDL.

Other improvements

• Package version is now exposed as clickhouse_connect.__version__, following Python packaging conventions.
• Lazy loading of optional dependencies (numpy, pandas, pyarrow, polars) now applies to the async client as well.
• Pandas 3.x compatibility.

Full RC notes

For the per-RC breakdown:

• v1.0.0rc1: all 1.0 breaking changes, plus initial bug fixes
• v1.0.0rc2: performance release
• v1.0.0rc3: insert retry / SYNTAX_ERROR fix