ClickHouse Connect

raw JSON →
0.15.1 verified Tue May 12 auth: no python install: draft

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.

pip install clickhouse-connect
error ModuleNotFoundError: No module named 'clickhouse_connect'
cause The 'clickhouse-connect' library is either not installed in the Python environment being used or there's an issue with the Python path.
fix
Ensure the library is installed using pip: pip install clickhouse-connect or python -m pip install clickhouse-connect. If using a virtual environment, activate it first. If in a Docker container, ensure it's included in the requirements.txt or Dockerfile.
error Failed to connect to the server. Please check that host, port and interface are correct.
cause The application could not establish a connection to the ClickHouse server, often due to an incorrect host, port, network connectivity issues, or the ClickHouse server not running or being inaccessible.
fix
Verify the ClickHouse server's host and port are correct (default HTTP port is 8123, HTTPS is 8443). Check network connectivity between your application and the ClickHouse server, ensure no firewalls are blocking the port, and confirm the ClickHouse server is running and configured to accept connections from your application's IP address (e.g., check listen_host in ClickHouse config).
error SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
cause This error occurs when `clickhouse-connect` tries to establish a secure (SSL/TLS) connection to ClickHouse, but the client cannot verify the server's SSL certificate. This is common with self-signed certificates or when the client's trust store is outdated or missing the necessary CA certificate.
fix
If connecting to ClickHouse Cloud, ensure secure=True is set in the connection and your client's IP is whitelisted. For self-signed certificates, specify the ca_cert parameter in clickhouse_connect.get_client pointing to your CA certificate file, or, for testing purposes, disable SSL verification by setting secure=False and verify=False (not recommended for production). You may also need to update system SSL certificates using pip install --upgrade certifi.
error DB::Exception: Authentication failed. Code: 516.
cause The provided username or password for connecting to ClickHouse is incorrect, or the user lacks the necessary privileges for the attempted operations.
fix
Double-check the username and password used in your clickhouse_connect.get_client call. Ensure they match the credentials configured on the ClickHouse server. Also, verify that the user has the required permissions (e.g., SELECT, INSERT, etc.) for the database and tables being accessed.
error DB::Exception: Cannot convert type String to UInt64
cause This error signifies a data type mismatch where a value of one type (e.g., String) is being used in a context that expects a different, incompatible type (e.g., UInt64), and ClickHouse cannot perform an implicit conversion. This often happens during data insertion or when comparing values in queries.
fix
Explicitly cast the data to the correct type using ClickHouse's CAST() function or type conversion functions like toInt64(), toString(), etc., within your SQL query or before inserting data. For example, CAST('123' AS UInt64) or toInt64('123'). Ensure your application's data types align with the ClickHouse table schema.
breaking The 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.
breaking Version 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.
breaking The 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]`.
deprecated Python 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.
gotcha Optional 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.
gotcha For 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.
gotcha When 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`).
breaking Installing `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.
pip install "clickhouse-connect[pandas,numpy,sqlalchemy,polars,arrow,async]"
python os / libc variant status wheel install import disk mem side effects
3.10 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async build_error - - - - - -
3.10 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async - - - - - -
3.10 alpine (musl) clickhouse-connect build_error - - - - - -
3.10 alpine (musl) clickhouse-connect - - - - - -
3.10 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async wheel 15.0s 0.27s 574M 10.5M clean
3.10 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async - - 0.30s 537M 10.5M -
3.10 slim (glibc) clickhouse-connect wheel 3.5s 0.27s 55M 10.5M clean
3.10 slim (glibc) clickhouse-connect - - 0.28s 55M 10.5M -
3.11 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async build_error - - - - - -
3.11 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async - - - - - -
3.11 alpine (musl) clickhouse-connect build_error - - - - - -
3.11 alpine (musl) clickhouse-connect - - - - - -
3.11 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async wheel 13.7s 0.54s 602M 12.0M clean
3.11 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async - - 0.77s 564M 12.0M -
3.11 slim (glibc) clickhouse-connect wheel 3.0s 0.49s 58M 12.0M clean
3.11 slim (glibc) clickhouse-connect - - 0.51s 58M 12.0M -
3.12 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async build_error - - - - - -
3.12 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async - - - - - -
3.12 alpine (musl) clickhouse-connect build_error - - - - - -
3.12 alpine (musl) clickhouse-connect - - - - - -
3.12 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async wheel 13.5s 0.70s 585M 12.0M clean
3.12 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async - - 0.85s 548M 12.0M -
3.12 slim (glibc) clickhouse-connect wheel 2.5s 0.67s 50M 12.0M clean
3.12 slim (glibc) clickhouse-connect - - 0.74s 50M 12.0M -
3.13 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async build_error - - - - - -
3.13 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async - - - - - -
3.13 alpine (musl) clickhouse-connect build_error - - - - - -
3.13 alpine (musl) clickhouse-connect - - - - - -
3.13 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async wheel 13.4s 0.70s 584M 12.2M noisy
3.13 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async - - 0.75s 546M 12.2M -
3.13 slim (glibc) clickhouse-connect wheel 2.5s 0.66s 49M 12.2M noisy
3.13 slim (glibc) clickhouse-connect - - 0.74s 49M 12.2M -
3.9 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async build_error - - - - - -
3.9 alpine (musl) pandas,numpy,sqlalchemy,polars,arrow,async - - - - - -
3.9 alpine (musl) clickhouse-connect build_error - - - - - -
3.9 alpine (musl) clickhouse-connect - - - - - -
3.9 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async wheel 16.6s 0.30s 507M 10.4M noisy
3.9 slim (glibc) pandas,numpy,sqlalchemy,polars,arrow,async - - 0.35s 507M 10.4M -
3.9 slim (glibc) clickhouse-connect wheel 3.8s 0.32s 55M 10.4M noisy
3.9 slim (glibc) clickhouse-connect - - 0.34s 55M 10.4M -

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}")