ClickHouse/clickhouse-connect v1.0.0rc1

on GitHub

Release Candidate 1.0.0

This is a release candidate for clickhouse-connect 1.0.0. Please test thoroughly with your workloads and report any issues before the final release.

Installation:

pip install clickhouse-connect==1.0.0rc1

Important Migration Notes

Python Version: Minimum Python version is now 3.10. If you're on Python 3.9, pin to clickhouse-connect<1.0 or upgrade Python.

Timezone Handling: The pytz dependency has been replaced with the standard library zoneinfo. On Windows, tzdata is pulled in automatically. On slim Linux containers, install with pip install clickhouse-connect[tzdata].

Async Client: The executor-based async client has been removed. Use clickhouse_connect.get_async_client() for a native aiohttp-based client. Install with pip install clickhouse-connect[async].

Pandas: Minimum pandas version is now 2.0.

What's Changed

Breaking Changes

• Dropped Python 3.9 support. Minimum supported Python version is now 3.10. 0.15.x is the last series supporting Python 3.9.
• Dropped the pytz dependency in favor of the standard library zoneinfo. On Windows, tzdata is pulled in automatically. On slim Linux containers without a system tzdb, install pip install clickhouse-connect[tzdata].
• Unknown timezone strings from query_tz, column_tzs, or the server now surface zoneinfo.ZoneInfoNotFoundError internally (previously pytz.exceptions.UnknownTimeZoneError). User-visible ProgrammingError/log messages suggest the tzdata extra. Closes #714.
• Removed the deprecated utc_tz_aware parameter entirely. Use tz_mode instead: "naive_utc" (default, was False), "aware" (was True), or "schema" (unchanged). Closes #654, #665
• Removed the deprecated apply_server_timezone parameter entirely. Use tz_source instead: "auto" (default), "server" (was True), or "local" (was False).
• Remove the legacy executor-based async client. The AsyncClient(client=...) constructor pattern, executor_threads, and executor parameters are no longer supported. Use clickhouse_connect.get_async_client() (or create_async_client()) which creates a native aiohttp-based async client directly. The pool_mgr parameter is also rejected on the async path. aiohttp remains an optional dependency, installed via pip install clickhouse-connect[async].
• The internal AiohttpAsyncClient class has been renamed to AsyncClient and the module clickhouse_connect.driver.aiohttp_client has been removed. Import AsyncClient from clickhouse_connect.driver as before.
• Dropped pandas 1.x support. Minimum pandas version is now 2.0. Users with pandas < 2.0 will get a NotSupportedError at import time. Non-pandas usage is unaffected. Closes #661
• Removed the preserve_pandas_datetime_resolution common setting. Datetime columns now always return their natural resolution, e.g. datetime64[s] for DateTime, datetime64[ms] for DateTime64(3), instead of coercing everything to datetime64[ns]. Closes #662

Bug Fixes

• Fix Dynamic/JSON column reads when a path's inferred type sorts alphabetically after "SharedVariant". ClickHouse's DataTypeVariant constructor sorts its members alphabetically by name, and discriminator bytes on the wire index into that sorted order. The client appended SharedVariant to the variant list without sorting, so affected paths were read as the wrong variant. Closes #712
• Fix async streaming race condition that caused unhandled InvalidStateError exceptions on early stream termination. When breaking out of an async stream early, shutdown() scheduled a set_result callback for pending futures via call_soon_threadsafe, but Task.cancel() could cancel the future before the callback ran. The done-check is now deferred into the callback itself so it sees the actual future state at execution time.
• SQLAlchemy: Wrap raw SQL strings in text() in ChClickHouseDialect.get_schema_names() and get_table_names(), so Inspector.get_schema_names() and get_table_names() work on SQLAlchemy 2.x instead of raising ObjectNotExecutableError.

Improvements

• Package version is now exposed as clickhouse_connect.__version__ (a string), following Python packaging conventions. The version remains single-sourced from clickhouse_connect/_version.py. Users can access version information via clickhouse_connect.__version__, importlib.metadata.version("clickhouse-connect"), or the clickhouse_connect.common.version() helper.
• Lazy loading of optional dependencies (numpy, pandas, pyarrow, polars) now applies to the async client as well, matching the pattern established in 0.15.0 for the sync client.
• Clearer error message when attempting to use the async client without aiohttp installed.
• The generic_args parameter is now properly parsed on the async client creation path, matching the sync client behavior.
• Pandas 3.x compatibility. Removed deprecated copy=False parameter from Series(), concat(), and astype() calls. Updated datetime insert path to use vectorized numpy conversion instead of element-by-element nanosecond arithmetic.

Development

• Replaced pylint with Ruff for linting and formatting. Double quotes are now the standard quote style. Bulk formatting commits are listed in .git-blame-ignore-revs. CI lint job no longer requires building C extensions or installing project dependencies, significantly reducing lint check time.