v1.7.0

clickhouse-connect 1.7.0

clickhouse-connect 1.7.0 adds SQLAlchemy support for JSON subcolumns and materialized CTEs, introduces more control over error messages and naive datetime inserts, and fixes issues across parameter binding, streaming, JSON decoding, DB-API, and SQLAlchemy.

Highlights

Features and improvements

• SQLAlchemy JSON columns now support storage-backed subcolumn access through column["segment"], column.subcolumn(...), and the typed json_subcolumn(...) helper. #899
• SQLAlchemy statements can create materialized CTEs through .cte(..., materialized=True) and cc_sqlalchemy.cte(...). This requires ClickHouse 26.3 or later with enable_materialized_cte and the analyzer enabled. #900
• show_clickhouse_errors="scrub" preserves useful server error details while removing the server URL and version trailer. Transport and streaming errors follow the same setting. Invalid values now raise ProgrammingError. #344
• The new naive_datetime_insert setting controls whether naive Python datetime values use the client host timezone or the column and server timezone. The default remains "local" for compatibility. #938

Bug fixes

• SQLAlchemy and DB-API now handle percent signs in identifiers correctly, including %2E JSON key encodings.
• datetime.time and datetime.timedelta query parameters now bind correctly for Time and Time64, including nested, negative, extended-duration, timezone-aware, and nanosecond values. SQLAlchemy inserts, comparisons, and literal_binds now support these values too. #919
• The DB-API module now provides the standard Binary, Date, Time, Timestamp, and ticks-based constructors. This also fixes SQLAlchemy LargeBinary inserts. #919
• Fractional DateTime64 values before the Unix epoch now serialize to the correct second. #938
• Nested compound types containing enum values with escaped quotes now parse correctly. #878
• Nested None values in arrays, tuples, and map-formatted maps now render as SQL NULL. #879
• Empty bytes inserted into non-nullable FixedString columns are now padded correctly. #880
• Settings unavailable through system.settings, including custom role settings, are now forwarded to ClickHouse for validation. #530
• SQLAlchemy reflection and metadata queries continue returning string identifiers when the global String format is configured as bytes. #920
• Removing SQL block comments no longer joins adjacent query tokens or causes incorrect client-side LIMIT handling. #928
• Native streaming now detects complete mid-stream ClickHouse exception blocks across transport chunk boundaries. #915
• DB-API Cursor.description now reports accurate top-level nullability and handles empty-result metadata probes more safely. #902, #907, #909
• Compound and temporal values stored in JSON shared data now decode to Python values instead of raw bytes. #897
• Async streaming cleanup now runs on the event-loop thread, preserving the original StreamFailureError when TLS queries fail mid-stream.

Compatibility notes

• Runtime compatibility branches for unsupported ClickHouse versions older than 25.8 have been removed. ClickHouse 25.8 is now the supported baseline.
• datetime.time and datetime.timedelta parameters are now quoted by the driver. Remove manual quotes around existing %(name)s placeholders. #919
• 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. #938

Installation

pip install clickhouse-connect