Introduction

• The main interfaces are the synchronous Client and native aiohttp-based AsyncClient in clickhouse_connect.driver. The driver package also provides query and insert contexts, streaming helpers, DB-API support, and lower-level HTTP methods.
• The clickhouse_connect.datatypes package serializes and deserializes ClickHouse types using the ClickHouse Native binary columnar format.
• The optional Cython extensions in clickhouse_connect.driverc accelerate common serialization, conversion, and buffering paths. A pure Python path remains available on platforms where the extensions cannot be built.
• The package ships PEP 561 type information, so downstream type checkers consume annotations for the public driver, DB-API, and SQLAlchemy surfaces.
• The SQLAlchemy dialect in clickhouse_connect.cc_sqlalchemy supports SQLAlchemy Core, schema reflection, ClickHouse-specific query clauses and table engines, and Alembic migrations. Basic ORM reads and inserts work, but the dialect is designed for analytical workloads rather than full unit-of-work ORM behavior.
• The core driver and ClickHouse Connect SQLAlchemy implementation are the preferred method for connecting ClickHouse to Apache Superset. Use the ClickHouse Connect database connection, or clickhousedb SQLAlchemy dialect connection string.

​

Requirements and compatibility

​

Installation

pip install clickhouse-connect

pip install "clickhouse-connect[async]"      # Native asyncio client
pip install "clickhouse-connect[pandas]"     # Pandas
pip install "clickhouse-connect[arrow]"      # PyArrow
pip install "clickhouse-connect[polars]"     # Polars
pip install "clickhouse-connect[sqlalchemy]" # SQLAlchemy dialect
pip install "clickhouse-connect[alembic]"    # SQLAlchemy and Alembic
pip install "clickhouse-connect[chdb]"       # Embedded chDB backend
pip install "clickhouse-connect[tzdata]"     # IANA time zones on minimal systems

• git clone the GitHub repository.
• Change to the project root and run pip install .. The build system installs Cython automatically to compile the optional C extensions.

​

Support policy

​

Basic usage

​

Gather your connection details

​

Establish a connection

• Connecting to a ClickHouse server on localhost.
• Connecting to a ClickHouse Cloud service.

​

Use a ClickHouse Connect client instance to connect to a ClickHouse server on localhost:

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="localhost",
    username="default",
    password="password",
)

​

Use a ClickHouse Connect client instance to connect to a ClickHouse Cloud service:

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="HOSTNAME.clickhouse.cloud",
    port=8443,
    username="default",
    password="your password",
)

​

Interact with your database

client.command(
    "CREATE TABLE new_table "
    "(key UInt32, value String, metric Float64) "
    "ENGINE MergeTree ORDER BY key"
)

row1 = [1000, "String Value 1000", 5.233]
row2 = [2000, "String Value 2000", -107.04]
data = [row1, row2]
client.insert("new_table", data, column_names=["key", "value", "metric"])

result = client.query("SELECT max(key), avg(metric) FROM new_table")
print(result.result_rows)
# Output: [(2000, -50.9035)]

client.close()

​

Embedded chDB backend

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT number FROM numbers(3)")
    print(result.result_rows)
    # Output: [(0,), (1,), (2,)]