v1.3.0

This release adds structured error codes on raised exceptions, Windows ARM64 wheels, and a set of bug fixes for the DB API cursor and server-side bind parameters.

Highlights

Features

• Structured error fields on exceptions. Server errors now expose a numeric code attribute with the ClickHouse error code and a name attribute with the symbolic name such as UNKNOWN_TABLE on DatabaseError and OperationalError. Callers can branch on exc.code instead of parsing the message string. code is set even when show_clickhouse_errors is disabled. Both default to None when unavailable, such as on transport errors. Closes #786.
• Windows ARM64 wheels. Wheels are now built and published for win_arm64 on CPython 3.10 through 3.14, including the free-threaded 3.14 build. Closes #785.

Bug Fixes

• Large query parameter payloads are now automatically sent as form data in the request body instead of the URL query string, so a large IN list or a high-dimensional vector embedding no longer produces a URL that intermediaries like nginx, AWS ALB, or CloudFront reject with HTTP 414. Queries using binary parameter binds are never promoted automatically and only use form encoding when form_encode_query_params=True is set. Applies to both sync and async clients. Closes #740.
• DB API Cursor.executemany no longer raises AttributeError when rows are passed as sequences instead of mappings. PEP 249 allows sequence rows, and consumers like Airflow's DbApiHook.insert_rows(executemany=True) pass tuples.
• uuid.UUID, IPv4Address, and IPv6Address values nested inside Array, Tuple, or Map server-side bind parameters are now quoted, fixing IN lists of UUIDs bound to {name:Array(String)} being rejected by the server. Closes #791.
• A datetime parameter whose name genuinely ends in _64 is no longer renamed when the query binds that exact name, fixing placeholders like {param_64:DateTime64(6)} being left unbound. SQLAlchemy hit this with server_side_params=True once a statement reached 64 anonymous parameters. The documented _64 convention still works as before. Closes #790.

Installation

pip install --upgrade clickhouse-connect

Full Changelog: v1.2.0...v1.3.0