ClickHouse Driver

clickhouse-driver is a Python client for ClickHouse that speaks the database’s native TCP protocol rather than the HTTP interface, giving faster, more efficient query execution and result streaming. It supports the full ClickHouse type system (Array, Nullable, LowCardinality, Decimal, Map, Tuple, JSON, and more), compression, TLS, and query settings.

It ships both a native client API and a DB-API 2.0 compatible interface (clickhouse_driver.dbapi), plus optional Cython-accelerated components for performance-critical paths and NumPy/Arrow integration for efficient bulk data transfer into scientific Python workflows.

What You Get

• Native TCP protocol client (faster than the HTTP interface) with Client.execute() for queries
• A DB-API 2.0 compatible interface (clickhouse_driver.dbapi) for use with existing SQL tooling
• Full ClickHouse type support (Array, Nullable, LowCardinality, Decimal, Map, Tuple, JSON, IPv4/IPv6, and more)
• Cython-accelerated read/write buffers for performance-critical serialization paths
• NumPy and Arrow integration for efficient bulk data transfer into analytics workflows

Common Use Cases

• Running analytical queries against ClickHouse from Python ETL or reporting scripts
• Bulk-loading large datasets into ClickHouse tables efficiently via the native protocol
• Integrating ClickHouse as a data source for pandas/NumPy-based data analysis pipelines
• Using ClickHouse through SQLAlchemy or other DB-API-based tools via the dbapi interface
• Streaming large query results block-by-block without loading everything into memory at once

Under The Hood

Architecture - The clickhouse_driver package centers on connection.py and client.py, which implement the native ClickHouse wire protocol (protocol.py), with columns/ housing per-type (de)serialization logic, streams/ handling block-by-block result iteration, and a separate dbapi/ subpackage layering PEP 249 (DB-API 2.0) semantics on top of the native client. Tech Stack - Core serialization hot paths (bufferedreader/bufferedwriter, varint) are implemented in Cython (.pyx/.c files) for performance, with optional numpy and arrow submodules for zero-copy-ish bulk data exchange, and TLS/compression support built directly into the connection layer. Code Quality - The tests/ directory contains roughly 70 test files covering type serialization, compression, TLS, DB-API behavior, and protocol edge cases, with coverage tracked via Coveralls and CI run through GitHub Actions across supported Python versions. API Design - The native Client(...).execute('SELECT ...') call pattern is minimal for simple queries, while the DB-API layer lets it slot into existing cursor.execute()-based tooling (e.g. SQLAlchemy), though users need to choose upfront between the native and DB-API surfaces depending on which ecosystem they’re integrating with.