build(deps): bump clickhouse-connect from 1.1.1 to 1.5.0

[dependabot]

Bumps clickhouse-connect from 1.1.1 to 1.5.0.

Release notes

Sourced from clickhouse-connect's releases.

v1.5.0

clickhouse-connect 1.5.0

This is a feature release focused on the SQLAlchemy and Alembic integration, alongside two important correctness fixes on the core driver. Alembic gains first-class support for ClickHouse-specific DDL, SQLAlchemy gains per-query settings and typed ClickHouse query chainables, and Variant columns gain a new lossless read format. On the driver side, this release fixes a data-corruption bug when decoding large varints on the compiled path and a QBit corruption bug for dimensions greater than 8.

Highlights

Features

• Alembic support for ClickHouse-specific DDL. New runtime Alembic operations cover skip indexes, projections, table settings, materialized views, and dictionaries, including plural add/drop helpers for indexes and projections. The plural helpers emit a single comma-joined ALTER TABLE so replicated deployments avoid the Code: 517 CANNOT_ASSIGN_ALTER race. Helpers render valid SQL in offline --sql mode. #839
• Per-query ClickHouse settings in SQLAlchemy. execution_options(settings={...}) now forwards per-query settings through the dialect and DB-API cursor for Core and text() statements, execute, executemany, and the bulk-insert path. Settings set at the connection or engine level compose with per-statement settings, and per-statement values take precedence, so a connection-level default applies to implicit ORM queries such as selectinload and lazy loads. #838, #846
• Chainable JOIN modifiers. A new Select.ch_join() lets ClickHouse JOIN modifiers be written in normal SQLAlchemy chaining style. It takes the strictness modifiers ALL, ANY, ASOF, SEMI, and ANTI, the GLOBAL distribution modifier, plus USING and CROSS as keyword arguments. The existing ch_join() factory is unchanged. #827
• Typed ClickHouse select. cc_sqlalchemy.select() returns a ClickHouseSelect exposing ch_join, final, sample, array_join, prewhere, and limit_by as typed methods, so static type checkers accept them without suppressions. The standard sqlalchemy.select() path is unchanged. #837
• typed read format for Variant columns. When two members of a Variant share a Python type, such as Variant(Float32, Float64), reading with the typed format wraps each value as a TypedVariant carrying both the value and its type_name, and these feed straight back into inserts. Enable per query with query_formats={'Variant': 'typed'} or globally with set_read_format('Variant', 'typed'). The default native format is unchanged. #825

Bug Fixes

• Fixed corruption of QBit columns with a dimension greater than 8 on native inserts and reads. Data written by earlier clients was stored incorrectly and should be re-inserted. See the upgrade note below. #866
• The compiled Cython response buffer now decodes LEB128 varint values of 2^31 and larger correctly. Each 7-bit group was shifted in signed 32-bit arithmetic before being widened, so any varint of 2^31 or more was truncated or corrupted. This affected string and nullable string column lengths and every other varint read on the compiled path. The pure Python reader was already correct. #828
• command() now returns an empty string for a read that produces an empty result set, instead of a truthy QuerySummary that made if result: misleading. #865
• DB API Cursor.executemany no longer falls off the bulk-insert fast path when an INSERT names backtick-quoted dotted columns such as the wire form of Nested sub-columns. unescape_identifier now removes backtick quoting from compound identifiers correctly, which previously degraded the operation to slow per-row execution and could raise ProgrammingError with dict rows and pyformat placeholders. #820

SQLAlchemy Bug Fixes

• MergeTree engine key clauses order_by, partition_by, primary_key, sample_by, and ttl now accept arbitrary SQL expressions such as col.desc(), func.cityHash64(a, b), tuple_(...), and interval TTL expressions, in scalar and list forms. Expression engines round-trip through repr() for Alembic autogeneration. #845
• has_database() now uses EXISTS DATABASE instead of querying system.databases. On servers from 25.10 through 26.4, system.databases omitted DataLakeCatalog and other remote databases by default, so has_database() reported False for databases that actually exist. #849
• MATERIALIZED and ALIAS columns now keep their comment, codec, and ttl options in generated DDL, and column clauses are emitted in the order ClickHouse requires, COMMENT then CODEC then TTL. This also fixes a pre-existing case where a column combining a codec with a comment produced invalid SQL. #856
• ClickHouseSelect now keeps its typed ClickHouse chainables after column-shape methods such as add_columns(), with_only_columns(), column(), and reduce_columns(). cc_sqlalchemy.select() also works on SQLAlchemy 1.4. #844
• Wrapping a ClickHouse type in a SQLAlchemy TypeDecorator no longer raises TypeError: result_processor() takes 0 positional arguments but 2 were given when reading results. #847
• The Alembic op.rename_table now emits RENAME TABLE old TO new instead of the ALTER TABLE old RENAME TO new form ClickHouse rejects. Standard SQLAlchemy indexes are filtered from ClickHouse autogenerate output, and Column(index=True), Index(...), op.create_index, and op.drop_index raise a clear Alembic error before partially applying DDL. Use op.add_clickhouse_index and op.drop_clickhouse_index for data-skipping indexes. #839
• Fixed several Alembic ClickHouse DDL helper edge cases: raw SQL fragments containing :name are no longer parsed as bind parameters, dictionary comments escape backslashes correctly, explicit schemas are honored for legal dotted table names, CREATE MATERIALIZED VIEW no longer accepts a misleading clickhouse_settings suffix, and custom ClickHouse operation objects render through autogenerate instead of raising ValueError. #839

Upgrade notes

• QBit dimension greater than 8. Values written by earlier clients were stored incorrectly on the wire. After upgrading, re-insert any affected QBit data. #866
• command() return value. A read that returns no rows now yields an empty string rather than a truthy QuerySummary. Code that relied on command() for a read always being truthy should check the returned value explicitly. #865

Installation

pip install clickhouse-connect

Full Changelog: ClickHouse/clickhouse-connect@v1.4.2...v1.5.0

v1.4.2

clickhouse-connect 1.4.2

Patch release with a single bug fix on top of 1.4.1. No new features and no breaking changes.

... (truncated)

Changelog

Sourced from clickhouse-connect's changelog.

1.5.0, 2026-07-15

Bug Fixes

• SQLAlchemy: the Alembic op.rename_table now emits RENAME TABLE old TO new. It previously emitted the standard ALTER TABLE old RENAME TO new, which ClickHouse rejects. Standard SQLAlchemy indexes are now filtered from ClickHouse autogenerate output, and Column(index=True), Index(...), op.create_index, and op.drop_index raise a clear Alembic error before partially applying DDL. Use the ClickHouse-specific op.add_clickhouse_index and op.drop_clickhouse_index helpers for data-skipping indexes. Part of #839.
• SQLAlchemy: fixed several Alembic ClickHouse DDL helper edge cases. Raw SQL fragments containing :name are no longer parsed as SQLAlchemy bind parameters, dictionary comments now escape backslashes correctly, explicit schemas are honored for legal dotted table names, CREATE MATERIALIZED VIEW no longer accepts a misleading clickhouse_settings suffix that ClickHouse stores inside the SELECT definition, and custom ClickHouse operation objects now render through Alembic autogenerate instead of raising ValueError. Part of #839.
• SQLAlchemy: ClickHouseSelect now keeps its typed ClickHouse chainables after column-shape methods such as add_columns(), with_only_columns(), column(), and reduce_columns(). cc_sqlalchemy.select() also works on SQLAlchemy 1.4. Closes #844.
• SQLAlchemy: wrapping a ClickHouse type in a SQLAlchemy TypeDecorator no longer raises TypeError: result_processor() takes 0 positional arguments but 2 were given when reading results. Closes #847.
• SQLAlchemy: MergeTree engine key clauses (order_by, partition_by, primary_key, sample_by, ttl) now accept arbitrary SQL expressions such as col.desc(), func.cityHash64(a, b), tuple_(...), and interval TTL expressions, in scalar and list forms. Expressions were previously either rejected with a TypeError in list form or rendered through the wrong dialect in scalar form. Plain strings, text(), and bare Column inputs render exactly as before, and expression engines round-trip through repr() for Alembic autogeneration. Closes #845.
• SQLAlchemy: has_database() now uses EXISTS DATABASE instead of querying system.databases. On ClickHouse servers from 25.10 through 26.4 system.databases omitted DataLakeCatalog and other remote databases by default, so has_database() reported False for databases that actually exist and broke schema-existence checks. EXISTS DATABASE consults the database catalog directly and is correct on every server version. Closes #849.
• SQLAlchemy: MATERIALIZED and ALIAS columns now keep their comment, codec, and ttl options in generated DDL. Column clauses are also now emitted in the order ClickHouse requires, COMMENT then CODEC then TTL, which fixes a separate pre-existing case where any column that combined a codec with a comment produced invalid SQL that the server rejected. DEFAULT, MATERIALIZED, and ALIAS remain mutually exclusive. Closes #856.
• DB API Cursor.executemany no longer silently falls off the bulk insert fast path when an INSERT names backtick-quoted dotted columns, the wire form of Nested sub-columns such as `directory`.`id`. unescape_identifier stripped only the outermost backtick pair, so the normalized column names kept their inner backticks and never matched the row dict keys. The comparison always failed, so the operation degraded to slow per-row execution, and with dict rows and pyformat placeholders it could raise ProgrammingError. unescape_identifier now removes backtick quoting from compound identifiers correctly. Closes #820.
• The compiled Cython response buffer now decodes LEB128 varint values of 2^31 and larger correctly. Each 7-bit group was shifted in signed 32-bit arithmetic before being widened to the 64-bit accumulator, so any varint of 2^31 or more was truncated or corrupted. This affected string and nullable string column lengths and every other varint read on the compiled path. The pure Python reader was already correct. Closes #828.
• command() now returns an empty string for a read that produces an empty result set, instead of a truthy QuerySummary that made if result: misleading. Closes #865.
• Native inserts and reads of QBit columns with a dimension greater than 8 no longer corrupt the vector. Data written by earlier clients was stored incorrectly and should be re-inserted. Closes #866.

Improvements

• SQLAlchemy: added runtime Alembic operations for ClickHouse-specific DDL. The new helpers cover skip indexes, projections, table settings, materialized views, and dictionaries, including plural add/drop helpers for indexes and projections. The plural index and projection helpers emit a single comma-joined ALTER TABLE, so replicated deployments avoid the Code: 517 CANNOT_ASSIGN_ALTER race that separate statements can trigger. Helpers render valid SQL in offline --sql mode, and helpers whose signature includes clickhouse_settings render that mapping as an inline SETTINGS clause. Closes #839.
• SQLAlchemy: added a chainable Select.ch_join() so ClickHouse JOIN modifiers can be written in normal SQLAlchemy chaining style instead of nesting the ch_join() helper inside select_from(). It takes the strictness modifiers ALL, ANY, ASOF, SEMI, and ANTI, the GLOBAL distribution modifier, plus USING and CROSS, all as keyword arguments, and chains so multi-join queries stay readable. The existing ch_join() factory is unchanged. Closes #827.
• SQLAlchemy: added cc_sqlalchemy.select() which returns a ClickHouseSelect. It exposes the ClickHouse chainable modifiers such as ch_join, final, sample, array_join, prewhere, and limit_by as typed methods so static type checkers accept them without suppressions. The existing sqlalchemy.select() path keeps working unchanged. Closes #837.
• SQLAlchemy: execution_options(settings={...}) now forwards per-query ClickHouse settings through the dialect and DB-API cursor instead of silently ignoring them. This works for Core and text() statements, connection-level execution options, execute, executemany, and the bulk-insert path, while continuing to use the existing client settings validation. Settings set at the connection or engine level compose with per-statement settings, with the per-statement value taking precedence for any key set at both levels, so a connection or engine level default applies to every execution including implicit ORM queries such as selectinload and lazy attribute loads without overriding explicit per-query settings. Closes #838 and #846.
• Added a typed read format for Variant columns. When two members of a Variant share a Python type, such as Variant(DateTime, DateTime64(3)) or Variant(Float32, Float64), the decoded value alone did not record which member produced it, so the originating ClickHouse type was unrecoverable. Reading with the typed format wraps each value as a TypedVariant carrying both the value and its type_name, and these values feed straight back into inserts. The default read format stays native and returns bare values as before, so existing behavior is unchanged. Enable it per query with query_formats={'Variant': 'typed'} or globally with set_read_format('Variant', 'typed'). Closes #825.

1.4.2, 2026-07-06

Bug Fixes

• Async inserts and queries with an in-memory body larger than 1 MiB no longer emit an aiohttp ResourceWarning about sending a large body directly with raw bytes. Closes #850.

1.4.1, 2026-06-30

Bug Fixes

• SQLAlchemy: importing the ClickHouse Alembic integration no longer changes Alembic autogenerate output for other database dialects. The ClickHouse renderers for CreateTableOp, AddColumnOp, and DropTableOp were registered as process-wide replacements with no dialect guard, because Alembic renderers have no per-dialect dispatch. Any non-ClickHouse autogenerate run in the same process then used the ClickHouse renderers, which dropped the nullable argument from columns whose nullability was not set explicitly and injected cc_sqlalchemy imports. The renderers now fall back to Alembic's built-in rendering for non-ClickHouse dialects. Closes #832.
• Several public AsyncClient methods now carry the return-type annotations their sync Client counterparts already had. close, close_connections, query_np, query_df, query_arrow, set_client_setting, and set_access_token were missing them, so downstream projects running mypy with --disallow-untyped-calls got no-untyped-call errors on calls like await client.close() once the package began shipping py.typed in 1.4.0. The async client surface is now fully annotated. This is a type-only change with no runtime effect. Closes #831.

1.4.0, 2026-06-29

Bug Fixes

• QueryResult.first_item and QueryResult.first_row now return None for an empty result set instead of raising IndexError. Both properties indexed element [0] without checking the row count, so they crashed when a query returned no rows. They now short-circuit on an empty result in both row-oriented and column-oriented mode. Closes #824.
• Cursor.executemany now correctly resets rowcount and reports the number of inserted rows after a bulk insert. Previously, rowcount retained the value from the previous operation. The insert summary is also appended to cursor.summary, consistent with the non-bulk path. In addition, passing a generator as seq_of_parameters no longer raises TypeError; the bulk-insert optimisation is now skipped for non-indexable iterables and the operation falls through to the row-by-row path as PEP 249 requires.
• Fixed a connection failure partway through reading a query result being silently treated as a complete result. The reader detected the broken stream but discarded the error once any rows had already been read, so a truncated result was returned as if it were whole. A mid-stream read failure now raises StreamFailureError, carrying the server-side error message when ClickHouse reported one. Closes #802.
• Client.insert_arrow and AsyncClient.insert_arrow no longer drop the transport_settings argument. It was passed positionally into the compression parameter, so transport settings were ignored and a non-empty value corrupted the request. It is now forwarded correctly.
• command now raises ProgrammingError when binary parameter binds are combined with command data or external data, instead of placing binary content into the URL query string. This applies to both the sync and async clients.
• Importing clickhouse-connect no longer emits a DeprecationWarning for the array 'u' type code. The compiled buffer module built an unused array.array('u', []) template at import time. The 'u' (wchar_t) code was deprecated and is scheduled for removal in 3.16, where this would have become an ImportError. The template is removed, which also lets projects that run with -W error import the package. Closes #815.
• The SQLAlchemy Nullable and LowCardinality DDL helpers are now functions that return a concrete ChSqlaType. They were classes whose __new__ returned a different type, which type checkers cannot model, so Array(LowCardinality(String)) raised a spurious mypy error despite working at runtime. Runtime behavior is unchanged. Closes #819.

Improvements

• The Cython extension modules now declare free-threading compatibility, so importing clickhouse-connect on a free-threaded Python build such as 3.14t no longer silently re-enables the GIL. As part of this change, ResponseBuffer.read_uint64 no longer uses a module level scratch buffer for its big-endian byte swap, which was the one piece of shared mutable state in the C modules. Building from source now requires Cython 3.1 or later. The CI test matrix now runs the full suite on free-threaded Python 3.14t as a non-blocking job. Free-threading support remains experimental.
• QueryResult.query_id now returns an empty string instead of None when the server reported no query id. This matches QuerySummary and makes the property consistently typed as str.
• clickhouse-connect now ships PEP 561 type information. The py.typed marker is included so downstream type checkers can use the package annotations. Closes #692.
• create_client, create_async_client, connect(), and the DB-API Connection constructor now accept None for port and database to request the driver's defaults, in addition to omitting them. Previously the public type hints exposed the internal sentinel values 0 for port and "__default__" for database, so callers had no clean way to say "not specified". None is now the documented, typed way to do that at every level. The old sentinel values are still accepted, so the change is backward compatible. Closes #801.

... (truncated)

Commits

• b878607 v1.5.0 release prep (#869)
• d0f838a fix QBit native insert and read for dimension > 8 (#868)
• 17e182a ci: add StressHouse PR-vs-main benchmark workflow (#864)
• ad8f75c docs: require a CHANGELOG entry for user-facing changes (#863)
• 5b9d55c fix command() returns empty string for empty result sets (#867)
• 3e53f6c Add Code of Conduct (#862)
• 63624be decode LEB128 varints >= 2^31 on the compiled cython path (#861)
• 776b67a add typed read format for Variant columns (#860)
• 72cf4f6 Add docs sync workflow to ClickHouse/ClickHouse (#859)
• d4729ec fix(driver): unescape compound backtick identifiers (#821)
• 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)

[dependabot]

Superseded by #48.