v0.10.0

What's Changed

Improvements

• Added SQLAlchemy core API support for ARRAY JOIN and FINAL modifier. Closes #579
• Added Python 3.14 support 🎉 (non-free-threaded build only; free-threaded builds are not yet supported). Closes #574
• Added utc_tz_aware parameter to client and query methods to opt in to returning timezone-aware UTC objects for DateTime/DateTime64 columns. Default behavior remains the same and returns tz naive objects for backward compatibility.
  • Note: this parameter will likely be removed and only return tz-aware dts in some future release. Closes #566
• Added executor parameter to AsyncClient constructor to allow passing a custom executor for async operations. This allows users to control the concurrency and thread pool used by the async client.

Bug Fixes

• Fixed DST fallback bug in DateTime and DateTime64 types caused by passing potentially ambiguous times to pd.DateTimeIndex constructor. Closes #585
• Fixed issue with JSON key dot escaping. Closes #571

New Contributors

• @prokofyevDmitry made their first contribution in #569
• @wiese-m made their first contribution in #583
• @meirdev made their first contribution in #578

Full Changelog: v0.9.2...v0.10.0

v0.9.2

What's Changed

• Updated python_requires to drop Python 3.8 and advertise support for 3.9–3.13
• Allow passing role as a field in the settings keyword argument to set a role for a specific query

New Contributors

• @svix-jbrown made their first contribution in #550

Full Changelog: v0.9.1...v0.9.2

v0.9.1

What's Changed

• Fixed typing issue that required numpy to be installed during clickhouse_connect import

Full Changelog: v0.9.0...v0.9.1

v0.9.0

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

v0.8.18 Collected bug fixes

What's Changed

• Fix SQLAlchemy execution error by using text() function by @lakako in #491
• Test fixes for main by @genzgd in #497
• Ensure types are returned even if there are no rows by @orian in #500
• Fix some issues with cursor behavior by @joe-clickhouse in #506
  • Reset cursor location after performing an execute.
  • Fix behavior of fetchall to only return rows from the current cursor location.
  • Fixes logic of fetchmany to respect size parameter.
• Added a standalone test file (tests/unit_tests/test_driver/test_cursor.py) for testing cursor behavior

New Contributors

• @lakako made their first contribution in #491
• @joe-clickhouse made their first contribution in #506

Full Changelog: v0.8.17...v0.8.18

v0.8.17 Transport settings

What's Changed

• Updates for 0.8.17 release by @genzgd in #488
• Add param extra_http_headers to query/command methods by @orian in #489
• Change extra_http_headers to transport_settings by @genzgd in #490

Full Changelog: v0.8.16...v0.8.17

v0.8.16 Collected Bug Fixes

What's Changed

• Gg/update test matrix by @genzgd in #464
• Fix CI tests with default user by @genzgd in #465
• Replace removal of ; in the loop line with rstrip by @sbobryshev in #472
• Docker test fixes by @genzgd in #473
• Update README.md doc link by @genzgd in #476
• Correct typing of create_client(host, username) by @biggerfisch in #482
• Release 0 8 16 by @genzgd in #485

New Contributors

• @sbobryshev made their first contribution in #472

Full Changelog: v0.8.15...v0.8.16

v0.8.15 AsyncInsert Close Fix

What's Changed

• Update test_tls.py reference by @emmanuel-ferdman in #455
• Gg/update test jwt by @genzgd in #458
• Fix memory leak in AsyncClient by @pufit in #457
• 0.8.15 release by @genzgd in #459
• Exclude 3.8 Aarch64 builds by @genzgd in #460

New Contributors

• @emmanuel-ferdman made their first contribution in #455
• @pufit made their first contribution in #457

Full Changelog: v0.8.14...v0.8.15

v0.8.14 Pandas Big Int Insert Fix

What's Changed

• Make all None by default arguments accept None value by @orian in #450
• Fix pandas large ints by @genzgd in #454

New Contributors

• @orian made their first contribution in #450

Full Changelog: v0.8.13...v0.8.14

v0.8.13 Fix access_token default

What's Changed

• fix: add default value for access token in HttpClient init by @lukasthalerINNIO in #448
• Bump version for release by @genzgd in #449

New Contributors

• @lukasthalerINNIO made their first contribution in #448

Full Changelog: v0.8.12...v0.8.13