# What changed in clickhouse-connect

> 296 changes in clickhouse-connect 0.10 to 1 from its official release notes, upgrade guides and advisories: 49 breaking, 4 deprecations, 52 new APIs and options. Each one cited. Sources checked 2026-11-12. HTML: https://unstale.sh/pypi/clickhouse-connect/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## clickhouse-connect 1

### Breaking changes

- Install the lz4 extra to continue using `compress="lz4"` on Python 3.14 and later. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Closing a client-owned pool now closes idle connections immediately. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Decimal256(S) now resolves to precision 76. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Rust supports Python row and column queries in non-UTC server and local timezones; this requires clickhouse-connect-core>=0.2.3. (1.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.11.0)
- The ClickHouse dialect now owns its type mapping, preventing shared-mapping changes from hanging binds or reflection; unresolved custom adaptations raise CompileError after 1024 steps. (1.10.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.1)
- Generated schema metadata and Alembic revisions use clickhousedb_* options so copies and migrations work with both drivers installed; mixed installs should rename ClickHouse Connect schema options to this prefix. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Rust NumPy object columns now contain UTC numpy.datetime64 cells instead of Python datetime cells; SQL NULL remains None. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Supported columns convert directly from decoded buffers, reducing conversion overhead while keeping existing output dtypes except for the nanosecond correction. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- The Alembic extra now requires Alembic 1.18 or later. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- SQLAlchemy now applies ClickHouse backslash escaping to literal strings, defaults, aliases, TTL clauses, comments, and Alembic comment operations; custom pre-escaping workarounds should be removed. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- SQLAlchemy union(), intersect(), and except_() now emit explicit DISTINCT operations; use the corresponding _all() methods when duplicate-preserving behavior is required. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- Runtime compatibility branches for unsupported ClickHouse versions older than 25.8 have been removed; ClickHouse 25.8 is now the supported baseline. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- The driver now quotes these parameters; remove manual quotes around existing `%(name)s` placeholders. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Compound and temporal values stored in JSON shared data now decode to Python values instead of raw bytes. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Set this setting to `legacy` to restore the previous host-timezone conversion behavior for naive datetime query parameters. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Naive datetime query parameters now represent wall time in the target timezone; set `common.set_setting("naive_datetime_binding", "legacy")` to restore the previous host-timezone conversion behavior. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- zstd compression now uses Python 3.14's stdlib compression.zstd or backports.zstd on Python 3.10–3.13, replacing the zstandard dependency while remaining supported on standard Python installs. (1.6.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.6.0)
- A read producing an empty result set now returns an empty string instead of a truthy QuerySummary, so callers should check the returned value explicitly. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Standard SQLAlchemy indexes are filtered from ClickHouse autogenerate output, and create-index operations now raise a clear Alembic error before applying DDL; use ClickHouse index helpers for data-skipping indexes. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Client.insert, AsyncClient.insert, and raw_insert now require column_names to be a Sequence rather than a bare Iterable; one-shot iterators such as generators already failed at runtime. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Raises ProgrammingError when binary parameter binds are combined with command data or external data, rather than placing binary content in the URL query string. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Building from source now requires Cython 3.1 or later. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Returns None for an empty result set instead of raising IndexError. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Returns an empty string instead of None when the server reports no query id, keeping the property consistently typed as str. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- A connection failure while reading a query result now raises StreamFailureError instead of silently treating the result as complete; it carries the server-side error message when available. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- DSNs passed to create_client or create_async_client now percent-decode the username, password, and database. Escape literal percent signs as %25; a username without a password sends an empty password. (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- The async client no longer retries aiohttp timeout, connector, or fingerprint errors, which can indicate an already delivered request or a configuration issue rather than a stale connection. (1.1.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.1)
- The async client now requires aiohttp>=3.9.0 to support the per-request TLS SNI override. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- The alembic extra now requires alembic>=1.16 to provide the operation kwargs used by the integration. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Raises NoSuchTableError for missing tables instead of returning {"text": None}. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Re-escapes quoted identifiers that contain unescaped inner occurrences of their surrounding quote character, while leaving valid pre-quoted identifiers unchanged. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- The directly imported AiohttpAsyncClient class has been renamed to AsyncClient. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md)
- The deprecated parameter has been removed; use tz_source instead. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md)
- Install the async extra to use the aiohttp-based async client. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md)
- The native aiohttp-based client is now the only async implementation; obtain it with get_async_client. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md), [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- The aiohttp_client module has been removed; the class moved to clickhouse_connect.driver.AsyncClient. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md)
- Datetime columns return their natural resolution: DateTime as datetime64[s], DateTime64(3) as datetime64[ms], DateTime64(6) as datetime64[us], and DateTime64(9) as datetime64[ns]. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md)
- The executor-based async client is removed; use clickhouse_connect.get_async_client() instead. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- pandas 1.x is no longer supported; pandas 2.0 is the minimum, and pandas use with an older version raises NotSupportedError. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md), [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- This common setting has been removed; datetime columns now return their natural resolution rather than being coerced to datetime64[ns]. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md), [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Python 3.9 is no longer supported; Python 3.10 is the minimum supported version. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md), [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Use tz_mode in place of utc_tz_aware, with naive_utc as the default and aware and schema as additional modes. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md), [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Use tz_source in place of apply_server_timezone, with auto as the default and server and local as alternatives. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md), [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- The deprecated parameter has been removed; use tz_mode instead. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md)
- Timezone handling now uses the standard-library zoneinfo module instead of pytz. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md), [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)

### New APIs and options

- A synchronous HTTP client can get its own connection pool by passing `dedicated_pool=True`. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Sync and async client ping methods accept an optional timeout in seconds, defaulting to 3. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Connections and cursors support with blocks and close on normal or exceptional exit; connection contexts do not manage transactions. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Adds native SQLAlchemy 2.0.44+ async support for buffered Core and ORM execution, DDL, reflection, and Alembic migrations through run_sync(). (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Opt-in Native Map reads can preserve duplicate keys and server-returned order; dictionary output remains the default, and inserts still require dictionaries. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Source builds now provide an explicit C-extension mode through this environment variable. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Adds Native query and insert support for Geometry in both codecs. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Adds support for all ClickHouse Interval types. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Adds typed-path configuration and canonical reflection for ClickHouse JSON columns. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Adds Native query and insert support for MultiPoint in both codecs; inserting it requires ClickHouse 26.8 or later. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Adds an opt-in Rust codec for queries, streaming variants, and inserts; rust_strict raises on unsupported paths instead of falling back to Python. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Adds standalone Variant reflection. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- SQLAlchemy JSON columns can access storage-backed subcolumns through this method. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- The typed SQLAlchemy helper accesses storage-backed JSON subcolumns. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- SQLAlchemy statements can create materialized CTEs with `.cte(..., materialized=True)` or `cc_sqlalchemy.cte(...)`; this requires ClickHouse 26.3 or later with the analyzer and `enable_materialized_cte` enabled. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Controls whether naive Python datetime inserts use the client host timezone or the column and server timezone; the default remains `local`. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- The `scrub` value retains useful server error details while removing the server URL and version trailer; transport and streaming errors follow the same setting, and invalid values raise `ProgrammingError`. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- A chdb:// DSN selects the experimental in-process chDB backend; chdb:///on/disk/path specifies a persistent database. (1.6.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.6.0)
- The new experimental chDB backend is selected with interface='chdb'; it runs queries against an embedded engine and supports query, insert, streaming, and Arrow client operations. A path argument enables persistence. (1.6.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.6.0)
- Alembic gains runtime operations for ClickHouse-specific DDL, including skip indexes, projections, table settings, materialized views, and dictionaries, with plural add/drop helpers for indexes and projections. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Returns a typed ClickHouseSelect with typed ch_join, final, sample, array_join, prewhere, and limit_by methods, allowing static type checkers to accept these methods without suppressions. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- SQLAlchemy execution options can pass per-query ClickHouse settings through Core and text statements, execute, executemany, and bulk inserts; per-statement values take precedence over connection- or engine-level settings. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- The typed read format for Variant columns returns TypedVariant values carrying the value and type_name, which can be inserted back without loss when members share a Python type. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Adds chainable SQLAlchemy JOIN modifiers for ALL, ANY, ASOF, SEMI, ANTI, GLOBAL, USING, and CROSS. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Adds a global way to enable the typed read format for Variant columns. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Client creation functions, connect(), and the DB-API Connection constructor now accept None to request the driver's default database. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Client creation functions, connect(), and the DB-API Connection constructor now accept None to request the driver's default port. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- DatabaseError and OperationalError expose the numeric ClickHouse error code, allowing callers to branch without parsing the message. The attribute is None when unavailable and is set even when show_clickhouse_errors is disabled. (1.3.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.3.0)
- DatabaseError and OperationalError expose the symbolic ClickHouse error name; the attribute is None when unavailable. (1.3.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.3.0)
- Array now subclasses sqlalchemy.types.ARRAY and exposes item_type. (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- Add custom HTTP headers to every request, including initialization queries sent during client creation; also available on create_async_client. (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- Opt in to server-side bind parameters with server_side_params=True; the dialect emits ClickHouse native placeholders instead of client-side string interpolation. Off by default. (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- Sync and async clients accept a callable that supplies an access token and is called again after an authentication failure to fetch a fresh token and retry once. (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- Adds Alembic schema migrations for ClickHouse, including autogeneration, upgrade and downgrade flows, and ClickHouse-specific DDL for supported operations, engines, and dictionaries. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Adds an import-compatible module to ease migration from clickhouse-sqlalchemy. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Adds SQLAlchemy support to reflect, create, and drop ClickHouse dictionaries. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- The public Alembic operations API now accepts clickhouse_settings, and rendered AddColumnOp migrations preserve extra ClickHouse kwargs on round-trip. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Adds chainable lambda expressions to SQLAlchemy select constructs for ClickHouse-specific queries. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Adds chainable ClickHouse-specific LIMIT BY support to SQLAlchemy select constructs. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Adds chainable ClickHouse-specific PREWHERE support to SQLAlchemy select constructs. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- The package version is exposed as clickhouse_connect.__version__ following Python packaging conventions. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)

### Performance

- Array column reads are faster with the C extensions across all query methods. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Each block is read in one executor call instead of one call per row, making streaming reads much faster. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Client creation is faster when the server uses a non-UTC IANA timezone. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Cython decoding of Date and Date32 columns is faster. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Python-codec reads of Map, nullable integer, nullable date, and timezone-aware nullable datetime columns are faster. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Eligible SQLAlchemy Core and ORM SELECTs skip the extra LIMIT 0 metadata query for empty results. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- DataFrame conversion and Arrow encoding run on a dedicated client worker, reducing event-loop stalls. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Large uploads use bounded writes to reduce event-loop stalls during TLS encryption, and eligible retry payloads are replayable. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Large response chunks feed the decoder in bounded slices, reducing temporary copies and peak memory for NumPy, Pandas, and Python results. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Responses that fit in one chunk no longer start a read-ahead thread. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Rust codec pandas results use Arrow buffers directly instead of first creating Python strings. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Reads are an order of magnitude faster for naive UTC and UTC-equivalent timezones. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Reads are significantly faster because values are built directly from the integer column instead of intermediate strings. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Inserts from numpy arrays are significantly faster with lower peak memory; matching-dtype, 1-D C-contiguous arrays are copied directly via memcpy. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Reads and writes are significantly faster, and reads avoid intermediate pair-tuple materialization. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)

### Behavior and default changes

- On Python 3.14 and later, `compress=True` compresses inserts with standard-library zstd because lz4 is no longer installed by default. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- A stored command statement now runs when supplied through query context. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Supported compound and scalar values, nullable defaults, and typed JSON null paths decode to Python objects; DataFrame results retain the decoded objects. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- NumPy and Pandas queries no longer require PyArrow for buffered or streamed results, including query(..., use_numpy=True). Explicit Arrow output and Arrow storage still require it. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Parameterized DB-API executemany() preserves SQL expressions and sends one request per parameter set; earlier writes remain committed if a later request fails. Use Client.insert() for Native bulk throughput. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- SQLAlchemy multi-row inserts now support dictionaries, tuples, and SQL expressions, including Pandas to_sql(method="multi"). (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Synchronous HTTP connections use operating-system socket buffer sizing for large uploads. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Expands parsing, reflection, query, and insert support across server-valid precisions. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- SQLAlchemy Select.with_hint() now emits SAWarning when an applicable table hint would otherwise be ignored; generated SQL remains unchanged. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- Settings unavailable through `system.settings`, including custom role settings, are now forwarded to ClickHouse for validation. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- order_by, partition_by, primary_key, sample_by, and ttl now accept arbitrary SQL expressions in scalar and list forms, and expression engines round-trip through repr() for Alembic autogeneration. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Appends the insert summary to cursor.summary after a bulk insert. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- The Cython extension modules declare free-threading support, so importing the package on a free-threaded build no longer silently re-enables the GIL; support remains experimental. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Large query parameter payloads are automatically sent as form data in the request body instead of the URL query string. Binary parameter binds are not promoted automatically and use form encoding only when form_encode_query_params=True. (1.3.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.3.0)
- Read paths now use the full query_retries budget for connection-error retries; insert and command paths still get one retry. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- The async client now uses server_host_name to override the TLS SNI and certificate hostname as well as the HTTP Host header. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Generated DDL now emits table comments, reflection supports no-op autogenerate, and comment changes or drops use ALTER TABLE ... MODIFY COMMENT. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Lazy loading of numpy, pandas, pyarrow, and polars now applies to the async client as well. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Install the tzdata extra for slim Linux containers without a system timezone database. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md)
- Unknown timezone strings raise ZoneInfoNotFoundError internally instead of pytz's UnknownTimeZoneError; user-visible errors remain ProgrammingError. (1.0.0) — [upgrade guide](https://github.com/ClickHouse/clickhouse-connect/blob/HEAD/MIGRATION.md)

### Tooling

- `insert_block` is now typed as an async iterable of bytes; runtime behavior is unchanged. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Return-type annotations were added to close, close_connections, query_np, query_df, query_arrow, set_client_setting, and set_access_token, preventing strict mypy no-untyped-call errors. (1.4.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.1)
- The package ships a PEP 561 marker so downstream type checkers can use its annotations. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)

### Fixes and other changes

- Async connection drops raise OperationalError or StreamFailureError instead of leaking aiohttp errors; mid-stream drops on both clients report StreamFailureError and preserve the original cause. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Per-call arguments from context are now applied. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Decoding is corrected for dates before 1601 and leap centuries such as 1600 and 2400. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Nanosecond precision is preserved for pandas.Timestamp binds and inserts at scales 7–9, and for Tuple, Nested, Map, and Variant parameters. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Enum names containing backslashes or control characters now parse and insert correctly. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Large queries are no longer form-encoded automatically, avoiding Field value too long errors. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- The Python codec now reads and inserts nullable points correctly, including NULLs. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- The Python codec now reads and inserts nullable tuples correctly, including NULLs. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- LIMIT 0 queries return empty results, object-column rows retain their shape, and numeric LowCardinality columns return every row. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Datetime parameters with names ending in `_64` no longer fail with KeyError. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- `use_none=False` now works with Nullable(Date) and Nullable(Date32). (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Context tz_mode is preserved across all query methods. (1.12.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.12.0)
- Synchronous HTTP retry delays and failed-response cleanup are fixed for HTTP 429, 503, and 504 codes. (1.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.11.0)
- Python 3.15 is supported with wheels, including experimental free-threaded 3.15t wheels; lz4 currently builds from source on 3.15. (1.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.11.0)
- Missing-table reflection supports both NoSuchTableError and NoResultFound handlers with the existing message. (1.10.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.1)
- Connections closed before final HTTP response headers arrive, including after progress headers, now follow the existing remote-close retry policy. (1.10.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.1)
- Inspection of regular, window, and materialized views is fixed while existing table enumeration remains compatible. (1.10.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.1)
- Alembic accepts reflected state versions when metadata omits the version, including nested types; unversioned legacy states match explicit version 0. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- In mixed installs with clickhouse-sqlalchemy, use clickhousedb:// or clickhousedb+connect:// to avoid conflicting provider registration. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Rust NumPy and Pandas results preserve nanoseconds in nullable scalar columns, including SimpleAggregateFunction aliases; unsupported scalar precisions fail consistently. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- SQLAlchemy uses aliases only for matching top-level expressions selected by the query; unselected and nested expressions render in full. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Internal DESCRIBE TABLE requests use their own query ID, while inserts retain the caller's ID, avoiding same-ID-running errors. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Synchronous Native cleanup waits for active reads and drains partially consumed HTTP chunks through the same parser; early Rust stream closure drains before releasing its iterator. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Their return annotations preserve the wrapped type. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- These aliases return correct durations and NaT for NULL values. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- result_rows works after result_columns has been materialized, including async queries with column_oriented=True. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Cleanup releases response sources once, handles closure during read-ahead startup, releases decoder workers after cancelled reads, and completes before async cancellation is re-raised. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- After remote close or HTTP 429/503/504, SQL execution retries only recognized reads; writes and other listed statements are not replayed. This applies through DB-API and SQLAlchemy. (1.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.10.0)
- Fixes Alembic version-table handling. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Arrow inserts now correctly quote table and database identifiers on both clients. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Fixes async cancellation, initialization, connection disposal, token-provider cleanup, and pool timeout handling. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Comments, quoted identifiers, and escaped strings containing LIMIT 0 no longer cause results to be discarded. Metadata probes returning rows raise InternalError without replay; use raw_query() for those queries. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- DateTime64 declarations must match the server schema; precision handling is fixed. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Fixes Decimal arithmetic in SQLAlchemy. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Fixes SQLAlchemy table-engine reflection. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Fixes timezone-aware Date and Date32 inserts. (1.9.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.9.0)
- Fixes rendering for Nested, named Tuple, AggregateFunction, and SimpleAggregateFunction columns. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Improves parsing for Dynamic arguments. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Improves parsing for generic Enum definitions. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- IPv6 host literals are bracketed correctly for sync and async connections. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Improves parsing for quoted type names. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Abandoned Rust streams now promptly release their response, socket, buffered data, and read-ahead thread. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- SQLAlchemy and Alembic now connect and reflect correctly when the Rust codec uses strict mode. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Rust streams now honor show_clickhouse_errors. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Fixes empty Tuple Native serialization, including nested and nullable forms. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Fixes dialect-aware DDL compilation for TypeDecorator. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Fixes member ordering that could write Native insert data under the wrong member type. (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- Fixes dialect-aware DDL compilation for with_variant(). (1.8.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.8.0)
- The synchronous client now sends a normalized / request path through forwarding HTTP proxies when proxy_path is not configured. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- SQLAlchemy inspectors bound to an Engine now support get_columns() on SQLAlchemy 2.x. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- SQLAlchemy ClickHouse types now implement the public literal processor contract for TypeDecorator and with_variant(). (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- The async client now preserves explicit proxy_path values without adding extra slashes. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- Queries ending with a semicolon, whitespace, or trailing comment now place client-appended FORMAT clauses correctly, and insert detection follows SQL token rules. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- SQLAlchemy inspectors bound to an Engine now support reflect_table() on SQLAlchemy 2.x, honoring include_columns and exclude_columns. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- Server-side query placeholders now recognize $ in valid parameter names while preserving raw binary binding and ambiguity checks. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- Literals containing percent signs now compile safely alongside bound parameters and in server-side parameter mode. (1.7.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.2)
- Column DDL using this option no longer raises AttributeError on SQLAlchemy 1.4 because the rendering helper is implemented locally. (1.7.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.1)
- Identifier quoting no longer forwards the removed force argument to SQLAlchemy's parent quote method, preventing a TypeError with SQLAlchemy 2.1. The optional force parameter remains available on the ClickHouse preparer for direct callers. (1.7.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.1)
- Cleanup now runs on the event-loop thread, preserving the original `StreamFailureError` when TLS queries fail mid-stream. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- The DB-API module now provides the standard `Binary` constructor, also fixing SQLAlchemy `LargeBinary` inserts. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- DB-API descriptions now report accurate top-level nullability and handle empty-result metadata probes more safely. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- The DB-API module now provides the standard `Date` constructor. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Query binding now handles `Time` and `Time64` values, including nested, negative, extended-duration, timezone-aware, and nanosecond values; SQLAlchemy inserts, comparisons, and `literal_binds` support them too. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Fractional values before the Unix epoch now serialize to the correct second. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Empty bytes inserted into non-nullable `FixedString` columns are now padded correctly. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Streaming now detects complete mid-stream ClickHouse exception blocks across transport chunk boundaries. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- These types now parse correctly when enum values contain escaped quotes. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Nested `None` values in arrays, tuples, and map-formatted maps now render as SQL `NULL`. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- SQLAlchemy and DB-API correctly handle percent signs in identifiers, including `%2E` JSON key encodings. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Removing SQL block comments no longer joins adjacent query tokens or causes incorrect client-side `LIMIT` handling. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- These queries continue returning string identifiers when the global `String` format is configured as bytes. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- The DB-API module now provides the standard `Time` constructor. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- The DB-API module now provides the standard `Timestamp` constructor. (1.7.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.7.0)
- Initialization no longer overwrites user-supplied session settings with generated defaults, matching the sync client. (1.6.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.6.0)
- When client certificates and an access token are both configured, requests now send mutual TLS authentication headers and the Authorization: Bearer header together, matching the sync client. (1.6.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.6.0)
- Async clients now emit URL query parameters in the same order as the sync client on every request. (1.6.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.6.0)
- If the sync client's capability probe errors, client creation now falls back gracefully and logs at debug level. (1.6.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.6.0)
- Dict-valued settings such as additional_table_filters no longer cause a quoted-string parse exception when passed through query()'s settings parameter. (1.6.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.6.0)
- Fixes helper edge cases involving raw SQL bind parsing, dictionary comment escaping, explicit schemas, materialized-view settings suffixes, and autogeneration of custom operation objects. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Retains typed ClickHouse chainables after column-shape methods, and cc_sqlalchemy.select() works on SQLAlchemy 1.4. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Correctly decodes LEB128 varint values of 2^31 and larger on the compiled path, preventing truncation or corruption of string lengths and other varint values. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Preserves the bulk-insert fast path for INSERT statements naming backtick-quoted dotted columns, avoiding slow per-row execution and related ProgrammingError failures. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Uses EXISTS DATABASE instead of system.databases, preventing existing remote databases from being reported as absent on affected server versions. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Generated DDL retains comment, codec, and ttl options and emits column clauses in ClickHouse's required COMMENT, CODEC, TTL order. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Emits RENAME TABLE old TO new rather than the ALTER TABLE form ClickHouse rejects. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Fixes corruption of QBit columns with dimensions greater than 8 on native inserts and reads; affected data written by earlier clients should be re-inserted. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Wrapping a ClickHouse type in a SQLAlchemy TypeDecorator no longer raises a result_processor TypeError when reading results. (1.5.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.5.0)
- Async request bodies larger than 1 MiB are wrapped in io.BytesIO and written in chunks, avoiding aiohttp ResourceWarnings. (1.4.2) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.2)
- Importing the ClickHouse Alembic integration no longer changes autogenerate output for other database dialects; their built-in renderers are used instead. (1.4.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.1)
- Importing the package no longer emits a DeprecationWarning for the array 'u' type code, allowing imports when warnings are errors. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Forwards transport_settings correctly instead of passing it positionally as compression. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Resets rowcount and reports the number of inserted rows after a bulk insert. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- The SQLAlchemy DDL helper is now a function returning a concrete ChSqlaType, avoiding a spurious mypy error in nested type expressions; runtime behavior is unchanged. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Returns None for an empty result set instead of raising IndexError. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- Cursor.executemany accepts a generator without raising TypeError and skips the bulk-insert optimization for non-indexable iterables. (1.4.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.4.0)
- DB API executemany no longer raises AttributeError when rows are sequences rather than mappings. (1.3.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.3.0)
- UUID, IPv4Address, and IPv6Address values nested inside Array, Tuple, or Map parameters are now quoted, fixing server rejection of bound UUID IN lists. (1.3.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.3.0)
- A datetime parameter whose name genuinely ends in _64 is no longer renamed when the query binds that exact name; the documented _64 convention remains unchanged. (1.3.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.3.0)
- Wheels are now published for Windows ARM64 on CPython 3.10 through 3.14, including the free-threaded 3.14 build. (1.3.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.3.0)
- SQLAlchemy dialect reflection is implemented, enabling MetaData.reflect() and Inspector.get_multi_columns(). (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- Line comments beginning with -- and no following space are stripped when classifying queries, so leading --sql-style comments on DDL are routed as commands. (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- bytes and bytearray parameters now render as ClickHouse string literals with each byte represented as \xHH, fixing inserts into FixedString and String columns through the SQLAlchemy dialect. (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- A datetime bound to a server-side DateTime64 placeholder now retains sub-second precision, including through Array and Tuple hints; plain DateTime binds are unchanged. (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- UDT-based types including UUID, IPv4/IPv6, JSON, Nested, geometry types, and AggregateFunction now return concrete Python type classes instead of None. (1.2.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.2.0)
- The sync client now retries stale keep-alive BrokenPipeError exceptions, in addition to ConnectionResetError. (1.1.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.1)
- The async client now retries stale keep-alive resets surfaced as ClientConnectionResetError, helping large async inserts recover from killed pooled connections. (1.1.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.1)
- The async client now retries stale keep-alive resets surfaced as ClientOSError, helping large async inserts recover from killed pooled connections. (1.1.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.1)
- The async client's ping() now routes through the configured proxy, so it no longer falsely returns False when the server is reachable only via that proxy. (1.1.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.1)
- SHOW ROW POLICIES and SHOW POLICIES queries are routed without appending FORMAT Native; empty row-policy SHOW results now return an empty string instead of QuerySummary. (1.1.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.1)
- Preserves aliases through compilation for multi-column ARRAY JOIN, fixing label loss during parallel array expansion. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Alembic renders column comments inline in CREATE TABLE and ADD COLUMN statements instead of using separate COMMENT ON COLUMN statements rejected by ClickHouse. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Reflected engines now populate settings from parsed engine kwargs, decoding ClickHouse string-literal escapes and preserving float-valued settings. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Alembic autogenerated migrations now render enum types, including nested container types, in the correct ClickHouse-compatible representation. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Error messages now report the resolved database name from currentDatabase() when schema was not provided, rather than literal None. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Sync raw_query now passes query_retries so its connection-error retries match the async counterpart. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Sync raw_stream now passes query_retries so its connection-error retries match the async counterpart. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- Preserves FINAL, SAMPLE, PREWHERE, and LIMIT BY modifiers when select() is built from ORM-mapped attributes. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- SQLAlchemy quotes string-valued engine and operation settings as ClickHouse string literals; numeric and boolean settings remain unchanged. (1.1.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.1.0)
- During connection-pool rotation, installs the new session before retiring the old one and waits for outstanding requests to release their lease; close() clears the session so post-close calls fail with ProgrammingError. (1.0.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.1)
- The async client resolves the ca_cert="certifi" shorthand to certifi.where(), matching the sync client instead of passing the literal string to SSL certificate loading. (1.0.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.1)
- Recognizes ClickHouse Fixed/UTC±HH:MM:SS timezones in column types, the X-ClickHouse-Timezone header, and SELECT timezone(), avoiding ProgrammingError except at the ±24:00:00 boundary. (1.0.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.1)
- SQLAlchemy renders ILIKE and NOT ILIKE expressions using native ClickHouse syntax rather than the generic lower(...) LIKE lower(...) fallback. (1.0.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.1)
- Retries once when aiohttp raises ServerDisconnectedError on a pooled keep-alive connection idle-closed by the server. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Fixes a race condition that caused unhandled InvalidStateError on early stream termination. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- The SQLAlchemy Bool type accepts and forwards **kwargs, fixing ORM model use and Table.to_metadata(). (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- CreateDatabase with engine="Replicated" now emits valid DDL. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Fixes reads when a path's inferred type sorts alphabetically after SharedVariant. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Fixes intermittent empty-query syntax errors when a pooled keep-alive connection is reset between attempts. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- Raw SQL strings are wrapped in text() so the method works on SQLAlchemy 2.x. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)
- The release adds compatibility with Pandas 3.x. (1.0.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v1.0.0)

## clickhouse-connect 0.15

### Breaking changes

- Formatting timezone-aware datetimes in bind expressions now uses the parameter type hint's timezone instead of server_tz. (0.15.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.15.1)

### New APIs and options

- Adds multi-column array expansion for parallel arrays. (0.15.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.15.0)
- Adds comprehensive ClickHouse JOIN support in SQLAlchemy, including strictness and distribution modifiers and USING syntax. (0.15.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.15.0)

### Performance

- Imports numpy, pandas, pyarrow, and polars lazily, making bare imports about four times faster. (0.15.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.15.0)

### Fixes and other changes

- Fixes chained `.final()` and `.sample()` calls silently overwriting each other. (0.15.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.15.0)
- Fixes quoting of the config_section argument. (0.15.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.15.0)
- Removes the py.typed marker that caused false type errors for mypy and pyright users. (0.15.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.15.0)
- Adds missing Replicated engine variants, including ReplicatedReplacingMergeTree. (0.15.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.15.0)
- Fixes sqlalchemy.values() to emit ClickHouse VALUES table function syntax. (0.15.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.15.0)

## clickhouse-connect 0.14

### Breaking changes

- The legacy experimental Object('json') type was removed in favor of the new JSON type in ClickHouse. (0.14.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.0)

### Deprecations

- Creating the legacy async client now emits a FutureWarning advertising the async-native client available for testing. (0.14.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.0)
- Pandas 1.x support is deprecated and will be removed in 1.0.0. (0.14.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.0)
- Replaces utc_tz_aware with options "naive_utc" (the default), "aware", or "schema"; the old parameter still works with a deprecation warning. (0.14.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.0)
- Replaces apply_server_timezone with options "auto" (the default), "server", or "local"; the old parameter still works with a deprecation warning. (0.14.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.0)

### New APIs and options

- The SQLAlchemy dialect now supports SAMPLE. (0.14.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.0)

### Behavior and default changes

- The compiled driverc modules are used by default again; set this environment variable to 0 to disable the Cython runtime path. (0.14.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.1)

### Fixes and other changes

- Empty ORM/DBAPI SELECT results now populate cursor.description when ClickHouse Native format returns no data blocks, restoring correct handling of empty result sets. (0.14.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.1)
- Read paths now decode shared variant data instead of returning raw binary with discriminator byte prefixes. (0.14.1) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.1)
- Experimental wheel builds are available for Python 3.14 free-threading on all platforms. (0.14.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.0)
- Fixes an issue where sending redundant settings is skipped. (0.14.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.14.0)

## clickhouse-connect 0.13

### Breaking changes

- Variant values are serialized using their native ClickHouse types; values matching no variant member now raise DataError instead of being stringified and delegated to the server. (0.13.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.13.0)

### New APIs and options

- Provides a helper to specify the target type when automatic dispatch cannot resolve a Variant value. (0.13.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.13.0)
- Adds the schema mode, which returns timezone-aware datetimes only for columns whose server schema explicitly defines a timezone, and naive datetimes for bare DateTime columns. (0.13.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.13.0)

### Tooling

- Adds type annotations to public API methods in Client, AsyncClient, HttpClient, and QueryResult. (0.13.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.13.0)

### Fixes and other changes

- Corrects the parameter type from builtin any to typing.Any. (0.13.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.13.0)
- SQLAlchemy now renders label aliases instead of full expressions, avoiding circular reference errors when an alias shadows a source column name in ClickHouse. (0.13.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.13.0)
- Recognizes UPDATE as a command so lightweight updates work correctly via client.query() and SQLAlchemy. (0.13.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.13.0)

## clickhouse-connect 0.11

### Breaking changes

- A network failure before any data is received now raises OperationalError instead of returning an empty result. (0.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.11.0)

### New APIs and options

- Support for exceptions raised mid-stream was added. (0.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.11.0)
- The QBit data type is now supported. (0.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.11.0)

### Behavior and default changes

- HTTP clients now auto-enable this setting so SELECT queries are cancelled on the server when the client disconnects. (0.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.11.0)
- Tables can now be created from PyArrow objects, including objects with datetime/timestamp types. (0.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.11.0)
- When not explicitly set, query_id is now generated client-side as a UUID4. (0.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.11.0)

### Fixes and other changes

- InsertContext state is reset on insert failure, avoiding reuse errors when data is passed separately. (0.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.11.0)
- With utc_tz_aware=False, DateTime columns with explicit UTC timezones now return naive datetimes regardless of the UTC-equivalent timezone name; UTC-equivalence checks also extend to Arrow queries. (0.11.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.11.0)

## clickhouse-connect 0.10

### New APIs and options

- SQLAlchemy core API now supports ARRAY JOIN. (0.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.10.0)
- The AsyncClient constructor accepts a custom executor, allowing users to control concurrency and the thread pool used for async operations. (0.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.10.0)
- SQLAlchemy core API now supports the FINAL modifier. (0.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.10.0)
- Client and query methods accept utc_tz_aware to opt in to timezone-aware UTC objects for DateTime/DateTime64 columns; the default remains timezone-naive. (0.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.10.0)

### Fixes and other changes

- Fixes a DST fallback bug in DateTime and DateTime64 caused by passing potentially ambiguous times to pd.DateTimeIndex. (0.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.10.0)
- Fixes an issue with escaping dots in JSON keys. (0.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.10.0)
- Python 3.14 is supported on non-free-threaded builds; free-threaded builds are not yet supported. (0.10.0) — [release notes](https://github.com/ClickHouse/clickhouse-connect/releases/tag/v0.10.0)