ClickHouse/clickhouse-connect v0.9.0

on GitHub

What's Changed

Breaking Changes

• WARNING: BREAKING CHANGE — Removed support for sqlalchemy 1.3 which reached its EOL in 2021. The minimum required version is now 1.4.40.
• WARNING: BREAKING CHANGE — Behavior for reading from IPv6 columns has changed:
  • With read_format='native', the client will always return ipaddress.IPv6Address objects, even for IPv4-mapped addresses (e.g., "::ffff:192.168.1.1"). Previously, the client returned ipaddress.IPv4Address objects for these cases. This change enforces type consistency and avoids surprising implicit conversions. If your application requires IPv4 objects, you can explicitly convert using the ipv4_mapped attribute of IPv6Address.
  • With read_format='string', the client will always return IPv6 string representations, e.g., "::ffff:192.168.1.1" instead of "192.168.1.1", for the same reasons as above. If you require only the IPv4 string, you can parse or truncate this in your application code.
  • Closes #493

Major Features

• Added support for SQLAlchemy 2.x. The minimum required version is 1.4.40. Closes #263
• Added Polars support for Arrow-based query and insert methods (query_df_arrow, query_df_arrow_stream, insert_df_arrow). This initial implementation provides basic dataframe conversion through the Arrow format, similar to how we support the pyarrow-backed pandas dataframes. Closes #111 and #542
• Added support for querying/inserting pyarrow-backed DataFrames:
  • query_df_arrow(): returns a pandas DataFrame with PyArrow dtype backend. Note that Arrow data types are preserved without additional conversions.
  • query_df_arrow_stream(): Streaming version of query_df_arrow() for processing large result sets.
  • insert_df_arrow(): Optimized insertion method for pandas DataFrames with PyArrow backend, which should provide better performance than standard insert_df().
• Added Time and Time64 type support. Closes #509
• Support for both pandas 1.x and 2.x.
• Added support for Nullable(JSON) types
• Added support for BFloat16 types

Improvements

• Add support for lightweight DELETE in sqlalchemy. Closes #382
• Added support for SELECT/JOIN operations via SQLAlchemy's core API (table operations and explicit statements--not ORM sessions-based queries)
• Added client connection option rename_response_column (default None) that allows the user to define how response columns are automatically renamed according to a predefined scheme. Helpful for stripping alias prefixes, etc. in potentially complex queries. Closes #228
• Add third-party library identifiers (name/version) in the User-Agent, e.g. pandas/2.2.5. Users can opt out by changing the common setting send_integration_tags to False.
• Added support for form encoding query parameters when using HTTP interface. This addresses #342. Query parameters can now be sent as form-encoded data in the request body by setting form_encode_query_params=True when creating the client. This is particularly useful for queries with large parameter payloads that might exceed URL length limits.
• Added support for special interval types. Closes #391
• Added new common setting option "preserve_pandas_datetime_resolution" (default is False) allowing pandas 2.x users to opt into (when set to True) using the additional pandas 2.x datetime64/timedelta64 resolutions of "s", "ms", "us". If set to False or using pandas 1.x, all datetime64/timedelta64 resolutions will be coerced to "ns". (See here for more info). Closes #165 and #531
• Tightens up type consistency of date-like objects when using query_df
• When writing to an IPv6 column type, the client will "promote" IPv4 addresses to IPv4-mapped IPv6 addresses to prevent write errors. Closes #498
• Changed AsyncClient.settings typing to Optional[Dict[str, Any]] to accept None inputs.
• Added more robust error handling and tests. Closes #508
• Replace the use of deprecated datetime.utcfromtimestamp

Bug Fixes

• Fixed an AttributeError on http.client when importing clickhouse_connect under certain circumstances
• Fixes problem with df inserts of Time and Time64 types. Closes #524

New Contributors

• @herbert-allium made their first contribution in #512
• @SkytAsul made their first contribution in #518
• @janwijbrand made their first contribution in #545
• @sanjams2 made their first contribution in #543

Full Changelog: v0.8.18...v0.9.0