NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #758 most downloaded on PyPI
ClickHouse Database Core Driver for Python, Pandas, and Superset
Last release 8 days ago
22 Sep 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
3 versions withdrawn
withdrawn after publishing
4 years old
147 releases · first in 2022
One column per quarter.
Fix dataframe insert mutation by @genzgd in https://github.com/ClickHouse/clickhouse-connect/pull/113
Full Changelog: https://github.com/ClickHouse/clickhouse-connect/compare/v0.5.5...v0.5.6
Queries of LowCardinality columns using pandas or numpy query methods would result in an exception. https://github.com/ClickHouse/clickhouse-connect/i
Several performance improvements, especially for Pandas Dataframes.
Several performance improvements, especially for Pandas Dataframes.
with Context to stream data (this ensures the underlying
streaming response is properly closed/consumed.) For simple examples, see the basic tests.
query_column_block_stream -- returns a generator of blocks in column oriented (Native) format. Fastest method for retrieving data in native Python formatquery_row_block_stream -- returns a generator of blocks in row oriented format. Used for processing data in a "batch" of rows at time while limiting memory usagequery_rows_stream -- returns a convenience generator to process rows one at a time (data is still loaded in ClickHouse blocks to preserve memory)query_np_stream -- returns a generator where each ClickHouse data block is transformed into a Numpy arrayquery_df_stream -- returns a generator where each ClickHouse data block is transformed into a Pandas Dataframeclient_name is now reported in a standardized way to ClickHouse (as the http_user_agent). For better tracking of your
Python application, use the new product_name common setting or set client_name get_client parameter to identify your product
as <your-product-name>/<product-version>.maxsize for concurrent HTTP connections to a single host was accidentally dropped in the 0.5.x release. It
has been restored to 8 for better performance when using multiple client objects.threading.local() variables to store context information during query processing. The architecture
has been changed to pass the relevant Query or Insert Context to transformation methods instead of relying on thread local
variables. This is significantly safer in an environment where multiple queries can conceivably be open at the same on the
same thread (for example, if using async functions).ClickHouseType to the QueryContext.ClickHouseType methods have been renamed to remove outdated references to native format (everything is native now)Correctly return QueryResult object when created as a context using a with statement. This fixes examples and the preferred context syntax for process
with statement. This fixes examples and
the preferred context syntax for processing query results. Thanks to John McCann Cunniff JrThis 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-clickhou
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).
Fix ping check in http client. Closes https://github.com/ClickHouse/clickhouse-connect/issues/96.
The clickhouse_connect get_client method (which proxies the driver.Client constructor) previously accepted arbitrary keyword arguments that were inter
The clickhouse_connect get_client method (which proxies the driver.Client constructor) previously accepted arbitrary
keyword arguments that were interpreted as ClickHouse server settings sent with every request. To be consistent with
other client methods, get_client now accepts an optional settings Dict[str, Any] argument that should be used instead
to set ClickHouse server settings.
The driver.HttpClient constructor previously accepted the optional keyword argument http_adapter, which could be used to
pass a custom requests.adapter.HttpAdapter to the client. ClickHouse Connect no longer uses the requests library (see
Dependency Changes below). Instead, the HttpClient constructor now accepts an optional pool_mgr keyword argument which
can be used to set a custom urllib.poolmanager.PoolManager for the client. In most cases the default PoolManager is
all that is needed, but multiple PoolManagers may be required for advanced server/proxy applications with many client instances.
requests library. The requests library is built on
urllib3, but ClickHouse Connect was utilizing very little of the added functionality.
Requests also has very restricted access to the urllib3 streaming API, which made adding additional compression methods
difficult. Accordingly, the project now interfaces to urllib3 directly. This should not change the public API (except as
noted in the warning above), but the HttpClient internals have changed to use the lower level library.query method now supports streaming. The returned QueryResult object has new streaming methods:
stream_column_blocks - returns a generator of smaller result sets matching the ClickHouse blocks returned by the native interface.stream_row_blocks - returns a generator of smaller result sets matching the ClickHouse blocks returned by the native interface,
but "pivoted" to return data rows.stream_rows - returns a generator that returns a row of data with each iteration.with context to ensure the stream is properly closed when done. In addition, two new properties
result_columns and result_rows have been added to QueryResult. Referencing either of these properties will consume the stream
and return the full dataset. Note that these properties should be used instead of the ambiguous result_set, which returns
the data oriented based on the column_oriented boolean property. With the addition of result_rows and result_columns the
result_set property and the column_oriented property are unnecessary and may be removed in a future release.zstd and lz4 compression, as well as brotli (br),
if the brotli library is installed. If the client compress method is set to True (the default), ClickHouse Connect will request compression
from the ClickHouse server in the order lz4,zstd,br,gzip,deflate, and will compress inserts to ClickHouse using lz4. Otherwise,
the client compress argument can be set to any of lz4, zstd, br, or gzip, and the specific compression method will be
used for both queries and inserts. While gzip is available, it doesn't perform as well as the other options and should normally not
be used.gzip performance is poor compared to lz4 and zstd. Using those compression methods by default
avoids the major performance degradation seen in https://github.com/ClickHouse/clickhouse-connect/issues/89.Documentation has been expanded to cover recent updates.
driver.tools module adds the function insert_file to simplify
directly inserting data files into a table. See the test file
for examples. This closes https://github.com/ClickHouse/clickhouse-connect/issues/41.{<name>:<datatype>}, the client will automatically convert the query* method
parameters dictionary to the appropriate http query parameters. Closes https://github.com/ClickHouse/clickhouse-connect/issues/49.clickhouse_connect.get_client command will now accept a standard Python dsn argument and extract host, port,
user, password, and settings (query parameters) from the dsn. Note that values for other keyword parameters will take
precedence over values extracted from the dsn.first_item, first_row, and row_count in the result.JSON inserts with the ujson failed, this has been fixed. https://github.com/ClickHouse/clickhouse-connect/issues/84
Fixed a major settings issue with connecting to a readonly database (introduced in v0.4.4)
Common settings were stored in an immutable named tuple and could not be changed. This is fixed.
Ignore all "transport settings" when validating settings. This should fix https://github.com/ClickHouse/clickhouse-connect/issues/80 for older ClickHo
The get_client method now accepts a http_adapter parameter to allow sharing a requests.HTTPAdapter (and its associated connection pool) across multipl
Global/common configuration options are now available in the clickhouse_connect.common module. The available settings are:
clickhouse_connect.common module. The available settings are:
autogenerate_session_id [bool] Whether to generate a UUID1 session id used for every client request. Defaults to True. Disabling this can facilitate client sharing and load balancing in some use cases.dict_parameter_format [str] Options are 'json' and 'map'. This controls whether parameterized queries convert a Python dictionary to JSON or ClickHouse Map syntax. Default to json for insert into Object('json') columns.invalid_setting_action [str] Options are 'send' and 'drop'. Client Connect normally validates and drops (with a warning any settings that aren't recognized by the Server or are readonly).
Changing this setting to 'send' will include such settings with the request anyway -- which will normally result in an error being returned.clickhouse_connect.get_client method now accepts a settings dictionary argument for consistency with other client methods.When inserting Pandas DataFrame values into a ClickHouse Nullable(Float*) column, a Float NaN value will be converted to a ClickHouse NULL.
This is a side effect of a Pandas issue where df.replace cannot distinguish between NaT and NaN values: https://github.com/pandas-dev/pandas/issues/29024
Numpy array read and write compatibility has been refined and performance has been improved. This fixes https://github.com/ClickHouse/clickhouse-conne
The settings, table information, and insert progress used for client inserts has been centralized in a new reusable InsertContext object. Client inser
### Bug Fixes * Fix read compression typo
Update QueryContext.updated_copy method to preserve settings, parameters, etc. https://github.com/ClickHouse/clickhouse-connect/issues/65
### New Features * Build Python 3.11 Wheels
Fix insert into JSON column from SQLAlchemy, and fix some SQLAlchemy 1.4 issues.
Fix insert into JSON column from SQLAlchemy, and fix some SQLAlchemy 1.4 issues.
Fix 'SHOW CREATE' issue. https://github.com/ClickHouse/clickhouse-connect/issues/61
"Queries" that do not return data results (like DDL and SET queries) are now automatically treated as commands. Closes https://github.com/ClickHouse/c
session_id is not specified in clickhouse_connect.get_clientFix for Superset large integers (now rendered as strings) Fix for UInt64 type being incorrectly signed
Fix for Superset large integers (now rendered as strings) Fix for UInt64 type being incorrectly signed
This release removes the deprecated row binary serialization for ClickHouse communications and fixes some Superset issues.
This release removes the deprecated row binary serialization for ClickHouse communications and fixes some Superset issues.
Add single retry for HTTP RemoteDisconnected errors from the ClickHouse Server. This prevents exception spam when requests (in particular inserts) are
This release fixes a minor bug where the Superset connection dialog would incorrectly display connection errors if using the default port
This release fixes a minor bug where the Superset connection dialog would incorrectly display connection errors if using the default port
This release now creates binary wheels for most Python platforms.
This release now creates binary wheels for most Python platforms.
Your coding agent can read these notes before it upgrades. Set up the MCP server →