Skip to main content

Documentation Index

Fetch the complete documentation index at: https://private-7c7dfe99-page-updates.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

2025-11-14
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

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.9.2…v0.10.0
2025-09-25
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

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.9.1…v0.9.2
2025-09-17
v0.9.1

What’s Changed

  • Fixed typing issue that required numpy to be installed during clickhouse_connect import
Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.9.0…v0.9.1
2025-09-16
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

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.18…v0.9.0
2025-06-24
v0.8.18

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.17…v0.8.18
2025-04-13
v0.8.17

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.16…v0.8.17
2025-03-28
v0.8.16

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.15…v0.8.16
2025-01-25
v0.8.15

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.14…v0.8.15
2025-01-14
v0.8.14

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.13…v0.8.14
2025-01-07
v0.8.13

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.12…v0.8.13
2024-12-22
v0.8.11

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.10…v0.8.11
2024-12-15
v0.8.10
2024-11-27
v0.8.8
2024-11-01
v0.8.6

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.5…v0.8.6
2024-10-24
v0.8.5

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.4…v0.8.5
2024-10-08
v0.8.3

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.8.2…v0.8.3
2024-10-04
v0.8.2

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/V0.8.1…v0.8.2
2024-09-26
v0.8.0

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.19…v0.8.0
2024-08-21
v0.7.19
2024-07-30
v0.7.18

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.17…v0.7.18
2024-07-24
v0.7.17
2024-07-08
v0.7.16

Improvement

  • Added the AsyncClient wrapper which is intended for asyncio environment usage. AsyncClient has the same methods with the same parameters as the standard Client, but they are coroutines when applicable. Internally, these methods from the Client that perform I/O operations are wrapped in a run_in_executor call. See also the updated run_async example.
Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.15…v0.7.16
2024-07-01
v0.7.15

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.14…v0.7.15
2024-06-24
v0.7.14

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.12…v0.7.14
2024-06-04
v0.7.12
2024-05-27
v0.7.11

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.10…v0.7.11
2024-05-22
v0.7.10
Attempt fix of a pandas concatenation exception for some kinds of empty responses.
2024-05-21
v0.7.9

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.8…v0.7.9
2024-04-03
v0.7.7

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.6…v0.7.7
2024-03-28
v0.7.5

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.4…v0.7.5
2024-03-24
v0.7.4

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.3…v0.7.4
2024-03-14
v0.7.3

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.2…v0.7.3
2024-03-08
v0.7.2

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.7.1…v0.7.2
2024-02-28
v0.7.1
2024-01-22
v0.7.0
Drop Python 3.7 builds, minor updates

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.6.23…v0.7.0
2023-12-15
v0.6.23

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.6.22…v0.6.23
2023-12-01
v0.6.22

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.6.21…v0.6.22
2023-11-23
v0.6.21
2023-11-09
v0.6.20

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.6.19…v0.6.20
2023-10-25
v0.6.18
This reduces the block size for chunked inserts to avoid timeouts over HTTPS
2023-10-18
v0.6.16
Fixes an import problem on some Python installations, including RHEL
2023-10-17
v0.6.15
Build and CI tests for Python 3.12
2023-09-22
v0.6.14
Fix Python 3.7 import issue, 0 length FixedString Inserts
2023-09-20
v0.6.13

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.6.12…v0.6.13
2023-09-16
v0.6.12
Fixes index error on nested empty maps using native protocol
2023-08-27
v0.6.10
Allow use of the Object(Nullable(‘json’)) type, which is sometimes generated as a result of schema inference.
2023-08-22
v0.6.9
Improved insert error diagnostics, small packaging improvements.
2023-07-18
v0.6.8
2023-07-18
v0.6.7
Fixes an issue with reading some LowCardinality columns. Updates Cython to 3.0.0
2023-07-07
v0.6.6
2023-07-06
v0.6.5
Adds QuerySummary to insert queries, fixes several small issues

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.6.4…v0.6.5
2023-06-22
v0.6.4

What’s Changed

  • Fix issue when ClickHouse has no defaultdatabase
  • Fix SQLAlchemy dialect get_table_names method when database contains special characters
Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.6.3…v0.6.4
2023-06-16
v0.6.3
Fix float rounding for Decimal columns, and broken datetime64 dates before 1970
2023-06-10
v0.6.2

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.6.1…v0.6.2
2023-06-06
v0.6.1
Update Superset instructions
2023-06-06
v0.6.0

What’s Changed

Superset engine spec removed, multiprocessing fix with uuid4 session ids and urllib3 PoolManager per client, low level insert improvements.Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.25…v0.6.0
2023-05-23
v0.5.25
Fixes an issue with using clickhouse-connect with CHProxy and recent ClickHouse versions related to the client_protocol_version setting
2023-05-11
v0.5.24
Fixes bugs with external data, SimpleAggregateFunction inserts, and date/datetime server side parameter binding.
2023-05-03
v0.5.23
Some minor bug fixes, plus a new common setting max_connection_age

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/0.5.22…v0.5.23
2023-04-27
0.5.22

What’s Changed

zstd compression was broken with urllib3 (both the library and clickhouse-connect were decompressing the payload)Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.21…0.5.22
2023-04-26
v0.5.21

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.20…v0.5.21
2023-04-06
v0.5.20

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.19…v0.5.20
2023-04-05
v0.5.19

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.18…v0.5.19
2023-03-27
v0.5.17
2023-03-15
v0.5.16

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.15…v0.5.16
2023-03-10
v0.5.15

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.14…v0.5.15
2023-03-02
v0.5.14
Fixed bad pandas import, made optional import failure message less noisy.Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.13…v0.5.14
2023-02-15
v0.5.11

What’s Changed

New Contributors

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.10…v0.5.11
2023-02-13
v0.5.10
2023-02-10
v0.5.8

What’s Changed

Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.7…v0.5.8
2023-02-03
v0.5.6
2023-02-01
v0.5.5
2023-02-01
v0.5.4
Several performance improvements, especially for Pandas Dataframes.
2023-01-23
v0.5.3
2023-01-17
v0.5.2
This fixes issues where the client.database is set to None (that is not a common use case, but it can affect automated tests, such as for dbt-clickhouse).
2023-01-16
v0.5.1
2023-01-14
v0.5.0
2023-01-02
v0.4.8
2022-12-05
v0.4.7
2022-11-29
v0.4.6
2022-11-24
v0.4.5
2022-11-22
v0.4.4
2022-11-22
v0.4.3
2022-11-22
v0.4.2
2022-11-14
v04.1
Better support for Numpy arrays, including both object arrays and resizable matrices. Fix for an issue migrating Superset from clickhouse-sqlalchemy to clickhouse-connect
2022-11-07
v0.4.0
2022-11-04
v0.3.8
2022-11-04
v0.3.7
Improvs insert performance (and prevents timeouts) by using chunked transfer encoding and gzip compression (if compression is enabled)
2022-11-02
v0.3.6
2022-10-28
v0.3.5
2022-10-27
v0.3.4
Fix insert into JSON column from SQLAlchemy, and fix some SQLAlchemy 1.4 issues.
2022-10-21
v0.3.3
2022-10-20
v0.3.2
2022-10-19
v0.3.1
Fix for Superset large integers (now rendered as strings) Fix for UInt64 type being incorrectly signed
2022-10-15
v0.3.0
This release removes the deprecated row binary serialization for ClickHouse communications and fixes some Superset issues.
2022-09-28
v0.2.10
2022-09-25
v0.2.9
This release fixes a minor bug where the Superset connection dialog would incorrectly display connection errors if using the default port
2022-09-21
v0.2.8
This release now creates binary wheels for most Python platforms.
2022-09-08
v0.2.6
2022-08-30
v0.2.5
2022-08-19
v0.2.4
2022-08-14
v0.2.3
2022-08-07
v0.2.2
2022-08-04
v0.2.1
2022-08-04
v0.2.0
This release adds JSON support, fixes some SQLAlchemy related bugs, and introduces a new system for formatting query results.
2022-07-06
v0.1.6
Add support for Nested columns, small bug fixes
2022-06-27
v0.1.5
2022-06-17
v0.1.4
This fixes a breaking change where readonly settings would be sent to the ClickHouse server and cause queries to fail.
2022-06-17
v0.1.3
2022-06-16
v0.1.2
2022-06-11
v0.1.1
2022-06-09
v0.1.0
Beta release with improvements to client.command allowing separation of query from data.
2022-06-06
v0.0.15
Minor fixes to address deprecated APIs
2022-06-02
v0.0.14
2022-05-31
v0.0.13
Using the setting “metadata_only” or setting a query LIMIT of 0 will now correctly return column names and types in the QueryResult
2022-05-30
v0.0.12
Fix for PyPI release versions