v1.1.1

clickhouse-connect v1.1.1

This patch release fixes a handful of async-client connectivity bugs and a SHOW ROW POLICIES query routing issue. Recommended for all users on 1.1.0, especially those running the async client behind a proxy or against keep-alive-prone pools.

What's Changed

Bug Fixes

• Async client: ping() now routes through the configured proxy, matching _raw_request. Previously the proxy was omitted, so ping() falsely returned False on networks where the server was only reachable via the proxy. Closes #757.
• Fix query("SHOW ROW POLICIES") / query("SHOW POLICIES") by routing these non-tabular statements without appending FORMAT Native. Empty row-policy SHOW results now return "" instead of QuerySummary. Closes #761.
• Async client: retry stale keep-alive resets surfaced by aiohttp as ClientOSError or ClientConnectionResetError, fixing large async inserts on killed pooled connections. Closes #763.
• Async client: do not retry aiohttp timeout, connector, or fingerprint errors — these can indicate the request was already delivered or a config issue, not a stale connection.
• Sync client: also retry stale keep-alive BrokenPipeError (in addition to ConnectionResetError), matching the async behavior.

Installation

pip install clickhouse-connect

v1.1.0

clickhouse-connect 1.1.0

This is the first minor release on the 1.x line. 1.1.0 consolidates everything from the 1.1.0a1 and 1.1.0a2 alphas i.e. the Alembic/SQLAlchemy integration work and adds a handful of bug fixes on top of 1.0.1.

If you're upgrading from a 0.15.x or earlier release, please read MIGRATION.md for the 1.0 breaking changes first.

Regarding Alembic support

This is the first clickhouse-connect release to ship Alembic integration. SQLAlchemy and Alembic each have a large surface area, and ClickHouse has plenty of dialect-specific quirks, so this release should best understood as a focused first cut. The common autogenerate/upgrade/downgrade flows for tables, columns, engines, dictionaries, comments, and operation-level settings rather than an exhaustive port of every Alembic feature. If you hit a gap, an inconvenience, or unexpected behavior, please open an issue with a repro. Enhancement requests are equally welcome and will help prioritize what to focus on.

Highlights

SQLAlchemy & Alembic

• Alembic migration support. Full Alembic integration for ClickHouse schema migrations: autogeneration of migration scripts from SQLAlchemy metadata, upgrade/downgrade lifecycle, and round-tripping of ClickHouse-specific DDL. Supported operations include create/drop table, add/alter/drop/rename column, type and nullability changes, defaults, comments, IF EXISTS guards, column placement with AFTER, and operation-level clickhouse_settings. ClickHouse table engines (MergeTree, ReplacingMergeTree, etc.) and dictionaries are preserved through the migration lifecycle. Install via pip install clickhouse-connect[alembic]. See clickhouse_connect/cc_sqlalchemy/alembic/WORKED_EXAMPLE.md for an end-to-end walkthrough.
• ClickHouse Dictionary type support. Reflect, create, and drop ClickHouse dictionaries through SQLAlchemy and Alembic.
• New Select constructs: PREWHERE, LIMIT BY, and lambda expressions are now chainable on select() for ClickHouse-specific queries.
• Multi-column ARRAY JOIN label preservation. ARRAY JOIN aliases now survive through compilation, fixing label-loss issues with parallel array expansion.
• Migration shim for clickhouse-sqlalchemy users. New cc_sqlalchemy.types and cc_sqlalchemy.engines import-compatible modules ease migration from clickhouse-sqlalchemy. See clickhouse_connect/cc_sqlalchemy/MIGRATING_FROM_CLICKHOUSE_SQLALCHEMY.md.
• SQLAlchemy 1.4 and 2.x compatibility improvements across the dialect and DDL compiler paths.
• Inspector cloud quirk reflection fixes for ClickHouse Cloud-specific schema reflection edge cases.
• DDL compiler improvements including better handling of nested container types and Tuple adaptation.

Compatibility

• Async client now requires aiohttp>=3.9.0. This is required to support TLS SNI override via server_host_name, because aiohttp added the per-request server_hostname option in 3.9.
• The alembic extra now requires alembic>=1.16 (previously >=1.9), to expose the IF EXISTS / IF NOT EXISTS operation kwargs used by the integration.

Bug fixes

• Async client: server_host_name now also overrides the TLS SNI / certificate hostname, matching the sync client. Previously the async path only applied it to the HTTP Host header, so connecting to host A while presenting SNI B (the 0.x pool_mgr=urllib3.PoolManager(server_hostname=...) pattern, useful for ClickHouse Cloud VPC endpoints reached via external DNS) was not expressible against the new aiohttp-based client. Closes #752.
• Drain the full retries budget on connection-error retries in _raw_request instead of only retrying once. Previously both the sync and async clients gated network-error retries on attempts == 1, so two consecutive aiohttp.ServerDisconnectedErrors (or ConnectionResetErrors on the sync path) surfaced as OperationalError even when query_retries would have allowed another attempt. Read paths will now drain query_retries. Insert/command paths still get one retry. Sync raw_query and raw_stream, the foundation for query_arrow & query_arrow_stream now also pass query_retries so they match their async counterparts. Adds a 0.1 * attempts backoff between connection-error retries to match the 429/503/504 branch. Closes #754.
• quote_identifier now re-escapes inputs that start and end with ` or " but contain unescaped inner occurrences of the same quote character, instead of passing them through unchanged. Validly pre-quoted identifiers like backslash or doubled-quote escaping still pass through untouched. Closes #737.
• SQLAlchemy: op.add_column(..., clickhouse_settings={...}) now works through the public Alembic operations API. Previously the stock Operations.add_column proxy had a fixed signature that rejected clickhouse_settings with TypeError, even though the underlying impl accepted it. Rendered AddColumnOp migrations also preserve extra ClickHouse kwargs on round-trip, so autogenerated scripts containing clickhouse_settings=... survive regeneration.
• SQLAlchemy: Alembic migrations now handle comments with ClickHouse-compatible syntax. Column comments on CREATE TABLE / ADD COLUMN are rendered inline instead of emitting separate COMMENT ON COLUMN statements (which ClickHouse rejects). Table comments are now emitted in generated DDL, reflected for no-op autogenerate, and changed or dropped via ALTER TABLE ... MODIFY COMMENT. Inspector.get_table_comment(...) now raises NoSuchTableError for missing tables instead of silently returning {"text": None}.
• SQLAlchemy: quote string-valued engine and operation settings as ClickHouse string literals when rendering SETTINGS clauses. Previously settings like MergeTree(settings={"storage_policy": "hot_cold"}) or op.add_column(..., clickhouse_settings={"mutations_sync": "2"}) emitted unquoted SQL (storage_policy = hot_cold), which ClickHouse rejected. Numeric and boolean settings are unchanged.
• SQLAlchemy: preserve engine settings on reflection. build_engine() previously hardcoded engine.settings = {} even when the reflected DDL contained a SETTINGS clause, so callers reading engine.settings after reflection saw an empty dict. settings is now populated from the parsed engine kwargs, decoding ClickHouse string-literal escapes (\\, \', \n, etc.) and preserving float-valued settings as floats providing round-trip parity with the construction path.
• SQLAlchemy: Inspector error messages from get_table_metadata() now report the resolved database name i.e. from currentDatabase() when schema was not provided instead of literal None.
• SQLAlchemy: preserve FINAL, SAMPLE, PREWHERE, and LIMIT BY modifiers when a select() is built from ORM-mapped attributes e.g. select(Event.id) rather than Core columns. Previously the ORM compile path rebuilt the inner Select via Select._create_raw_select, which dropped the modifier instance attributes, so the compiled SQL silently emitted no modifier. The compiler now falls back to compile_state.select_statement which is the original user-built Select to recover the modifiers. Closes #730.
• Alembic autogenerated migrations now render enum types (including nested container types) with the correct ClickHouse-compatible representation.

Pre-release tags rolled into 1.1.0

• v1.1.0a1 (2026-05-06) - initial alembic / SQLAlchemy alpha
• v1.1.0a2 (2026-05-07) - ORM modifier compile-path fix

Install

pip install clickhouse-connect

For Alembic integration:

pip install clickhouse-connect[alembic]

v1.0.1

clickhouse-connect 1.0.1

If you are upgrading from 0.15.x or earlier, see MIGRATION.md for the 1.0 breaking changes.

What's Changed

Bug Fixes

• Recognize Fixed/UTC±HH:MM:SS timezones emitted by ClickHouse servers without an IANA tz database (in column types, the X-ClickHouse-Timezone header, and SELECT timezone()). Previously these raised ProgrammingError on any column read, parameter bind, or client init that touched one. The exact ±24:00:00 boundary remains rejected because Python's datetime.timezone cannot represent it. Closes #702.
• Async client: drain in-flight requests before closing the underlying aiohttp session. Sharing a single AsyncClient across concurrent coroutines previously raised RuntimeError: Session is closed (and related Connection reset / QUERY_WITH_SAME_ID_IS_ALREADY_RUNNING cascades) whenever max_connection_age triggered a pool rotation while other tasks had requests in flight. close_connections() now installs the new session before retiring the old one, and waits for outstanding requests (including streaming responses) to release their lease before tearing it down. close() clears self._session so post-close calls fail with ProgrammingError instead of leaking aiohttp's RuntimeError. Closes #744.
• Async client: ca_cert="certifi" shorthand now resolves to certifi.where(), matching the sync client. Previously the async path passed the literal string to ssl_context.load_verify_locations, producing FileNotFoundError. Closes #742.
• SQLAlchemy: render ILIKE and NOT ILIKE expressions using native ClickHouse syntax instead of the generic SQLAlchemy lower(...) LIKE lower(...) fallback.

v1.0.0

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

v1.1.0a2

1.1.0a2 — Alpha Preview (Bug-fix follow-up)

Quick follow-up to 1.1.0a1, rebased on 1.0.0rc3 so the rc3 insert-retry fix is included. Everything from 1.1.0a1 still applies. See that release for the full preview overview.

Installation

pip install clickhouse-connect==1.1.0a2

# To use the Alembic integration:
pip install "clickhouse-connect[alembic]==1.1.0a2"

Fixed in this preview

• SQLAlchemy: ClickHouse Select modifiers preserved through the ORM compile path. FINAL, SAMPLE, PREWHERE, and LIMIT BY were silently dropped when a select() was built from ORM-mapped attributes (e.g. select(Event.id)) rather than Core columns. The ORM compile path rebuilds the inner Select via Select._create_raw_select, which discarded the modifier instance attributes — so the compiled SQL emitted no modifier. The compiler now falls back to compile_state.select_statement to recover them. Closes #730.
• Inserts: rebuild body on connection-reset retry (inherited from 1.0.0rc3). Fixes intermittent Code: 62. Empty query. (SYNTAX_ERROR) on inserts when a pooled keep-alive connection is reset between attempts; the retry path now rebuilds the insert body instead of replaying an already-drained generator. Affects both sync and async clients. Closes #731.

Feedback

Please keep filing issues at https://github.com/ClickHouse/clickhouse-connect/issues with the alembic or sqlalchemy label.

Full changelog

See CHANGELOG.md for the complete entry.

v1.0.0rc3

Release Candidate 1.0.0 (rc3)

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.0rc3

If upgrading from 0.15.x, see the migration notes in rc1. All 1.0 breaking changes were introduced there. rc3 contains no new breaking changes.

Highlights

rc3 is a small bug-fix release on top of rc2. It fixes an intermittent SYNTAX_ERROR on inserts when a pooled keep-alive connection is reset between attempts.

What's Changed

Bug Fixes

• Fix intermittent Code: 62. Empty query. (SYNTAX_ERROR) on inserts when a pooled keep-alive connection is reset between attempts. The retry path now rebuilds the insert body instead of replaying an already-drained generator. Affects both sync and async clients. Closes #731

v1.1.0a1

1.1.0a1 — Alpha Preview (Alembic Integration)

This is an alpha preview of the upcoming 1.1.0 release, published from the joe/alembic-integration-work branch for early testing of the new SQLAlchemy and Alembic features. It includes everything in 1.0.0rc2 plus the additions listed below.

Installation

Pre-releases are not installed by default. Pin the exact version:

pip install clickhouse-connect==1.1.0a1

# To use the new Alembic integration:
pip install "clickhouse-connect[alembic]==1.1.0a1"

What's new in this preview

• Alembic migration support: Full Alembic integration for ClickHouse schema migrations: autogeneration from SQLAlchemy metadata, upgrade/downgrade lifecycle, and round-tripping of ClickHouse-specific DDL. Engines (MergeTree, ReplacingMergeTree, etc.) and Dictionaries are preserved through the migration lifecycle. Supported operations include create/drop table, add/alter/drop/rename column, type and nullability changes, defaults, comments, IF EXISTS guards, column placement with AFTER, and operation-level clickhouse_settings. See WORKED_EXAMPLE.md for an end-to-end walkthrough.
• ClickHouse Dictionary type support in SQLAlchemy and Alembic.
• New SQLAlchemy chainables: PREWHERE, LIMIT BY, and lambda expressions as Select constructs for ClickHouse-specific query shapes.
• Multi-column ARRAY JOIN label preservation — aliases now survive through compilation, fixing label loss with parallel array expansion.
• Migration shim for clickhouse-sqlalchemy users — new cc_sqlalchemy.types and cc_sqlalchemy.engines import-compatible modules. See MIGRATING_FROM_CLICKHOUSE_SQLALCHEMY.md.
• SQLAlchemy 1.4 and 2.x compatibility improvements across the dialect and DDL compiler paths.
• Inspector: cloud quirk reflection fixes for ClickHouse Cloud-specific schema reflection edge cases.
• DDL compiler: better handling of nested container types and Tuple adaptation.
• Alembic autogenerated migrations rendering enum types (including nested container types) with the correct ClickHouse-compatible representation.

Feedback

This alpha exists to shake out the new SQLAlchemy/Alembic surface before it ships in 1.1.0 final. Please file issues at https://github.com/ClickHouse/clickhouse-connect/issues with the alembic or sqlalchemy label so they're easy to triage.

Full changelog

See CHANGELOG.md for the complete entry, plus everything inherited from 1.0.0rc2.

v1.0.0rc2

Release Candidate 1.0.0 (rc2)

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.0rc2

If upgrading from 0.15.x, see the migration notes in rc1. All 1.0 breaking changes were introduced there. rc2 contains no new breaking changes.

Highlights

rc2 is primarily a performance release. There is order-of-magnitude faster DateTime/DateTime64 reads, Decimal reads, and fixed-width numpy inserts, plus significantly faster Map reads and writes.

What's Changed

Improvements

• Order-of-magnitude faster DateTime and DateTime64 reads for naive UTC and UTC-equivalent timezones. The Cython read paths now decode via epoch arithmetic and construct datetime objects directly via the CPython datetime C API, bypassing datetime.fromtimestamp and the Python-level datetime(...) constructor. Also fixes Cython DateTime conversion bugs and expands epoch-arithmetic test coverage.
• Significantly faster Map reads and writes. The read path avoids materializing an intermediate pair tuple. The write path moves into a new Cython build_map_columns helper.
• Order-of-magnitude faster fixed-width numeric inserts from numpy arrays, with significantly lower peak memory. A new Cython write_native_col helper writes 1-D C-contiguous numpy arrays of matching dtype directly into the output buffer via memcpy, avoiding the per-element conversion the previous path required.
• Significantly faster Decimal and BigDecimal reads. The decode path no longer constructs intermediate strings per row, building values directly from the integer column via Decimal.scaleb.

Bug Fixes

• Async client: retry once when a pooled keep-alive connection is closed by the server and aiohttp raises ServerDisconnectedError with the default "Server disconnected" message. The existing retry path covered "Connection reset" and "Remote end closed", but not the bare ServerDisconnectedError() produced by recent aiohttp versions, which surfaced as an OperationalError("Network Error: Server disconnected") on the first request after an idle period.
• SQLAlchemy Bool type now accepts and forwards **kwargs to the underlying SqlaBoolean constructor. SQLAlchemy's SchemaType machinery passes internal kwargs (e.g., _create_events) when copying or adapting the type during ORM model use or Table.to_metadata(), which previously raised a TypeError. Fixes #705
• SQLAlchemy: CreateDatabase with engine="Replicated" now emits a closing ) after the (zoo_path, shard, replica) arguments, fixing previously invalid DDL on this path. The same arguments and the system.tables lookup in get_engine now go through bound parameters and the existing format_str helper instead of raw f-string interpolation.

v1.0.0rc1

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.

v0.15.1

Bug Fixes

• Use timezone from parameter type hint instead of server_tz when formatting tz-aware datetimes in {param:Type} bind expressions. Fixes #697