Registry / database / clickhouse-connect

clickhouse-connect

JSON →
library0.15.1pypypi✓ verified 50d ago

ClickHouse Connect is the official Python driver for ClickHouse, providing a high-performance core database interface for Python applications, Pandas DataFrames, NumPy arrays, PyArrow tables, Polars DataFrames, and Apache Superset integration. It leverages the ClickHouse HTTP interface for maximum compatibility and is actively maintained with regular updates.

databasedata
pip install clickhouse-connect
Install & Compatibility
Where this runs
tested against v1.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.960 runs
build_error
glibc
py 3.103.960 runs
installs and imports cleanly · install 9.4s · import 0.501s · 586MB
485MB installed
● package 485MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

get_client
from clickhouse_connect import get_client
import clickhouse_connect

This quickstart demonstrates how to establish a connection to a ClickHouse server, create a table, insert data, and query it. It includes an example using the `query_df` method for Pandas DataFrames, which requires the `pandas` optional dependency. Credentials are loaded from environment variables for secure usage.

import clickhouse_connect import os host = os.environ.get('CH_HOST', 'localhost') port = int(os.environ.get('CH_PORT', 8123)) # Use 8443 for TLS/Cloud username = os.environ.get('CH_USER', 'default') password = os.environ.get('CH_PASSWORD', '') database = os.environ.get('CH_DB', 'default') try: client = clickhouse_connect.get_client( host=host, port=port, username=username, password=password, database=database, secure= (port == 8443) # Automatically use TLS for 8443 ) # Test connection client.ping() print(f"Successfully connected to ClickHouse at {host}:{port}") # Create a table client.command( "CREATE TABLE IF NOT EXISTS my_test_table (", " id UInt64,", " name String,", " value Float64", ") ENGINE MergeTree ORDER BY id" ) print("Table 'my_test_table' created or already exists.") # Insert data data_to_insert = [ [1, 'Alpha', 100.1], [2, 'Beta', 200.2], [3, 'Gamma', 300.3] ] client.insert('my_test_table', data_to_insert, column_names=['id', 'name', 'value']) print("Data inserted into 'my_test_table'.") # Query data result = client.query('SELECT * FROM my_test_table ORDER BY id') print("Query Results:") for row in result.result_set: print(row) # Example with Pandas (requires 'pandas' extra) try: import pandas as pd df = client.query_df('SELECT * FROM my_test_table') print("\nPandas DataFrame Results:") print(df) except ImportError: print("\nSkipping Pandas example: 'pandas' not installed. Install with `pip install clickhouse-connect[pandas]`") finally: if 'client' in locals(): client.close() print("Connection closed.") except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
breakingThe parameter `apply_server_timezone` in client and query methods was renamed to `tz_source` in v0.14.0.
fix
Replace `apply_server_timezone=True` (or similar) with `tz_source='auto'` or other valid options for timezone handling.
affects: >=0.14.0
breakingVersion 0.13.0 introduced a native write path for the `Variant` data type. Previously, values were stringified; now they are serialized using their native ClickHouse types client-side, which changes how `Variant` columns store data.
fix
Review insertion logic for `Variant` columns. Ensure that your application expects native type serialization. If using older ClickHouse server versions with `Variant`, compatibility issues may arise.
affects: >=0.13.0
breakingThe legacy executor-based asynchronous client (`AsyncClient(client=...)`) and related parameters (`executor_threads`, `executor`, `pool_mgr`) have been removed. The native aiohttp-based async client is now standard.
fix
Migrate to `clickhouse_connect.get_async_client()` or `create_async_client()`, which uses `aiohttp`. Ensure `aiohttp` is installed via `pip install clickhouse-connect[async]`.
affects: future 0.15.x releases (already removed in 0.15.0 changelog, listed as UNRELEASED breaking change prior to 0.15.0)
deprecatedPython 3.9 support is deprecated and will be removed in version 1.0. Python 3.8 is End-of-Life (EOL) and no longer officially tested or supported; wheels are not built for 3.8 AARCH64 versions.
fix
Upgrade to Python 3.10 or higher. The library officially tests against Python 3.10 through 3.14.
affects: Python 3.8 (unsupported), Python 3.9 (deprecated)
gotchaOptional dependencies (e.g., `numpy`, `pandas`, `pyarrow`, `polars`, `sqlalchemy`) are lazy-loaded. If you intend to use features relying on these, you must install them explicitly using the `[extra]` syntax (e.g., `pip install clickhouse-connect[pandas]`).
fix
Always install necessary extras for features like Pandas DataFrame integration, even if the base `clickhouse-connect` package is already present.
affects: >=0.15.0
gotchaFor ClickHouse server versions 22.8 and 22.10+, there is an internal serialization format incompatibility for experimental JSON. Using multiple clients with mixed 22.8/22.9 and 22.10+ server versions will break if JSON support is enabled. Pandas 1.x support is also deprecated and will be dropped in 1.0.
fix
For JSON, use separate Python interpreters for different ClickHouse server versions if mixed JSON usage is required. For Pandas, upgrade to Pandas 2.x or later.
affects: ClickHouse server versions 22.8/22.9 vs 22.10+, clickhouse-connect <1.0 for Pandas 1.x
gotchaWhen creating a DBAPI Connection or SQLAlchemy DSN, unrecognized keyword arguments or query parameters will now raise an exception instead of being passed as ClickHouse server settings. Server settings should be prefixed with `ch_`.
fix
Prefix any ClickHouse server-specific settings passed as keyword arguments or query parameters with `ch_` (e.g., `ch_max_rows_to_read=1000`).
affects: >=0.9.0
breakingInstalling `clickhouse-connect` in minimal environments (e.g., `alpine` Docker images) may fail if a C compiler is not present. The `lz4` dependency, required by `clickhouse-connect`, often needs to be built from source if a pre-built wheel is unavailable for the specific Python version and architecture, which necessitates a C compiler (like `gcc`).
fix
Ensure that build-essential packages are installed in your environment (e.g., `apk add build-base` for `alpine` Linux) before attempting to install `clickhouse-connect`, or use a Python base image that includes a C compiler.
affects: All versions of `clickhouse-connect` in environments lacking C compilers (e.g., `alpine` Linux), particularly for newer Python versions where `lz4` wheels might be unavailable.
Upgrade
Version history
1.2.0latest on PyPI
Audit
Dependencies
certifirequiredRequired for secure connections.
urllib3requiredHTTP client library (>=1.26).
pytzrequiredTimezone handling.
zstandardrequiredZSTD compression support.
lz4requiredLZ4 compression support.
sqlalchemyoptionalSQLAlchemy Core dialect and Superset integration.
numpyoptionalIntegration with NumPy arrays and Pandas DataFrames.
pandasoptionalIntegration with Pandas DataFrames.
polarsoptionalIntegration with Polars DataFrames.
pyarrowoptionalIntegration with PyArrow tables and Arrow-backed Pandas DataFrames.
aiohttpoptionalRequired for the native asynchronous client.
Agent activity
61 hits · last 30 days
node
10
ahrefsbot
3
seranking-bot
3
amazonbot
1
Resources