chore(deps): bump clickhouse-connect from 1.1.1 to 1.3.0

[dependabot]

Bumps clickhouse-connect from 1.1.1 to 1.3.0.

Release notes

Sourced from clickhouse-connect's releases.

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: ClickHouse/clickhouse-connect@v1.2.0...v1.3.0

v1.2.0

clickhouse-connect 1.2.0

This release adds opt-in server-side bind parameters for the SQLAlchemy dialect, a token_provider client option for refreshable access tokens, and custom HTTP headers on client creation. It also ships a batch of SQLAlchemy reflection and type fixes along with several correctness fixes in query parameter handling and DSN parsing.

⚠️ Upgrade note: literal % in a DSN

The dsn passed to create_client / create_async_client now percent-decodes the username, password, and database. This lets you supply credentials that contain reserved characters in URL-encoded form, so pass%20word decodes to pass word.

If your DSN contains a literal %, you must now escape it as %25. A DSN credential like pa%ss will otherwise be misread. This is the one behavior change in this release that can affect existing setups, so check your connection strings before upgrading. A DSN with a username and no password now also sends an empty password rather than the literal string None. Closes #713.

Highlights

New features

• Server-side bind parameters for SQLAlchemy. Opt in with create_engine(url, server_side_params=True). The dialect then emits ClickHouse native {name:Type} / {name:Array(Type)} placeholders instead of client-side string interpolation. Off by default. Closes #735.
• token_provider client option. Sync and async. It accepts a callable that returns an access token string. The callable is invoked once for the initial token and again to fetch a fresh token whenever the server rejects the current one on an authentication failure, retrying the request once. Mutually exclusive with access_token and username/password.
• Custom HTTP headers. A new headers option on create_client / create_async_client attaches custom headers to every request, including the initialization queries sent during client creation. Useful for HTTP gateways that require auth headers such as Cloudflare Access service tokens.

Bug fixes

• A datetime bound to a server-side {name:DateTime64(...)} placeholder now keeps its sub-second precision instead of being truncated to seconds. The declared parameter type drives this, so no _64 name suffix or manual DT64Param wrapper is needed, and it applies through Array and Tuple hints. Plain DateTime binds are unchanged. Closes #739.
• bytes / bytearray query parameters now render as ClickHouse string literals, each byte as \xHH, instead of the Python repr. This fixes inserts into FixedString / String columns through the SQLAlchemy dialect. Closes #777.
• Strip -- line comments that have no following space when classifying queries, so a DDL with a leading --sql-style comment is routed as a command instead of raising StreamFailureError. Closes #499.

SQLAlchemy improvements

... (truncated)

Changelog

Sourced from clickhouse-connect's changelog.

1.3.0, 2026-06-11

Improvements

• Build and publish Windows ARM64 win_arm64 wheels for CPython 3.10 through 3.14, including the free-threaded 3.14 build. Closes #785.
• Server errors now expose structured fields on the raised exception. DatabaseError and OperationalError carry a numeric code attribute with the ClickHouse error code and a name attribute with the symbolic name such as UNKNOWN_TABLE, so callers can branch on exc.code instead of parsing the message string. code is set even when show_clickhouse_errors is disabled. name is only set when error detail is enabled. Both default to None when unavailable, such as on transport errors. Closes #786.

Bug Fixes

• DB API Cursor.executemany no longer raises AttributeError: 'tuple' object has no attribute 'keys' when rows are passed as sequences instead of mappings. The bulk insert optimization assumed every row was a dict, but PEP 249 allows seq_of_parameters to contain sequences, and cursor.execute already accepted positional parameters. Sequence rows now use the same bulk insert path, taking column names from the INSERT statement when present. This fixes consumers like Airflow's DbApiHook.insert_rows(executemany=True), which passes tuples.
• Large query parameter payloads are now automatically sent as form data in the request body instead of the URL query string. Server-side bind parameters were urlencoded into the request URL, so a large IN list or a high-dimensional vector embedding could produce a URL that HTTP intermediaries such as nginx, AWS ALB, and CloudFront reject with HTTP 414. The client now routes parameters to the POST body once their encoded length passes a threshold, which keeps the URL small. Setting form_encode_query_params=True still forces form encoding for all queries. Queries using binary parameter binds are never promoted automatically and only use form encoding when the flag is set. This does not change the server's per-value size limit, which is governed by http_max_field_value_size. Applies to both sync and async clients. Closes #740.
• uuid.UUID, IPv4Address, and IPv6Address values nested inside Array, Tuple, or Map server-side bind parameters are now quoted, matching client-side parameter formatting. Previously they rendered unquoted, so an IN list of UUIDs bound to {name:Array(String)} (as produced by SQLAlchemy Column.in_ with server_side_params=True) was rejected by the server with Code: 26 ... cannot be parsed as Array(String). Closes #791.
• A datetime parameter whose name genuinely ends in _64 is no longer renamed when the query binds that exact name. bind_query treated any trailing _64 as a DateTime64 precision hint and stripped it before looking at the query, so a placeholder like {param_64:DateTime64(6)} was left unbound and the server rejected the query. SQLAlchemy hits this with server_side_params=True once a statement reaches 64 anonymous parameters. The suffix is now only treated as a hint when the full name does not appear as a placeholder in the query, which leaves the documented _64 convention working as before. Closes #790.

1.2.0, 2026-06-08

Improvements

• SQLAlchemy: opt-in server-side bind parameters via create_engine(url, server_side_params=True). The dialect then emits ClickHouse native {name:Type} / {name:Array(Type)} placeholders instead of client-side string interpolation. Off by default. Closes #735.
• Added a token_provider client option (sync and async). It accepts a callable returning an access token string; the callable is invoked once for the initial token and again to fetch a fresh token whenever the server rejects the current one (authentication failure), retrying the request once. Mutually exclusive with access_token and username/password.
• Added a headers option to create_client/create_async_client for attaching custom HTTP headers to every request, including the initialization queries sent during client creation. Useful for HTTP gateways that require auth headers such as Cloudflare Access service tokens.

Bug Fixes

• A datetime bound to a server-side {name:DateTime64(...)} placeholder now keeps its sub-second precision instead of being truncated to seconds. The declared parameter type drives this, so no _64 name suffix or manual DT64Param wrapper is needed, and it applies through Array and Tuple hints. Plain DateTime binds are unchanged. Closes #739.
• Strip -- line comments that have no following space when classifying queries, so a DDL with a leading --sql-style comment is routed as a command instead of raising StreamFailureError. Closes #499.
• SQLAlchemy: implement reflection on the dialect itself so MetaData.reflect() and Inspector.get_multi_columns() work.
• SQLAlchemy: UDT-based types (UUID, IPv4/IPv6, JSON, Nested, geometry types, AggregateFunction, etc.) now return concrete python_type classes instead of None, matching SQLAlchemy's TypeEngine.python_type contract.
• SQLAlchemy: Array now subclasses sqlalchemy.types.ARRAY and exposes item_type.
• bytes/bytearray query parameters now render as ClickHouse string literals (each byte as \xHH) instead of the Python repr, fixing inserts into FixedString/String columns through the SQLAlchemy dialect. Closes #777.
• The dsn passed to create_client/create_async_client now percent-decodes the username, password, and database, so credentials containing reserved characters can be supplied URL-encoded (pass%20word becomes pass word). A literal % in a DSN must now be written as %25. A DSN with a username and no password now sends an empty password rather than the literal string None. Closes #713.

Commits

• e6e5fd4 1.3.0 release prep (#796)
• 72a0ae7 Fix dbapi Cursor.executemany crashing on sequence rows (#795)
• aaddb19 expose ClickHouse error code and name on raised exceptions (#788)
• 89cadee fix _64 param-name suffix stripping when the full name is a query placeholder...
• 98c1106 fix uuid and ip address bind parameters rendering unquoted inside containers ...
• 4976348 auto-promote large query parameters to form body (#789)
• 9c7bae4 add windows arm64 wheel builds (#787)
• 895e974 avoid qemu in wheel builds (#784)
• 3bcbcc9 v1.2.0 release prep (#783)
• 6e54147 Add client-level HTTP headers (#776)
• Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

---

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)