clickhouse-driver

What it is and what it does

Clickhouse-driver is a native TCP client library for ClickHouse, the columnar analytics database. It provides two interfaces: a direct Client class for executing queries and retrieving results, and a DB API 2.0 compliant connection interface for applications expecting standard Python database semantics. The driver handles ClickHouse's native protocol directly rather than HTTP, supporting features like compression, TLS encryption, query settings, external data, and block-by-block result streaming. It includes comprehensive type support for ClickHouse's data types (integers, floats, dates, strings, arrays, tuples, maps, JSON, and more) and can work with multiple hosts.

The package depends on pytz and tzlocal for timezone handling, which is essential for ClickHouse's DateTime and DateTime64 types. It is actively maintained, supports Python 3.9 through 3.14, and has been in development since 2017. The library is positioned for developers building analytics applications, data pipelines, or tools that need to query ClickHouse clusters from Python.

Use it for:

• Execute analytical queries against ClickHouse and retrieve results in a Python application.
• Build ETL pipelines that insert bulk data into ClickHouse tables using parameterized queries.
• Integrate ClickHouse as a backend for a web application using the DB API 2.0 interface.
• Stream large result sets block-by-block to avoid loading entire datasets into memory.
• Query ClickHouse with TLS encryption and compression for secure, efficient network communication.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A native TCP driver for ClickHouse that executes queries and returns results, supporting both a direct client interface and Python DB API 2.0 specification.

Yes. The package is actively maintained, has no known vulnerabilities, supports modern Python versions, and provides both low-level and DB API interfaces suitable for different use cases. Medium install friction is typical for compiled drivers and poses no practical barrier. MIT licensing imposes no restrictions. Install if you need to query ClickHouse from Python.

Install

clickhouse-driver on PyPI

pip install clickhouse-driver

uv add clickhouse-driver

poetry add clickhouse-driver

Installing clickhouse-driver

Before you install

Medium install friction due to compiled wheels across multiple architectures and Python versions (3.9–3.14). Active maintenance with a recent release 28 days ago and ongoing repository activity suggests reliable support.

License in practice

MIT license permits use in commercial and proprietary projects with minimal restrictions; attribution is required but no copyleft obligations apply.

Quickstart

pip install clickhouse-driver

from clickhouse_driver import Client
client = Client('localhost')
result = client.execute('SELECT 1')
print(result)

ClickHouse server must be running and accessible at the specified host.

Verify before relying

• Whether NumPy array support requires an additional optional dependency or is built-in.
• Default port and connection parameters for the Client.
• Support for asynchronous operations (description references aioch wrapper but does not detail native async support).

Package facts

Evidence: clickhouse_driver-0.2.11-cp310-cp310-macosx_10_9_x86_64.whl; clickhouse_driver-0.2.11-cp310-cp310-macosx_11_0_arm64.whl; clickhouse_driver-0.2.11-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; clickhouse_driver-0.2.11-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl; clickhouse_driver-0.2.11-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl; clickhouse_driver-0.2.11-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; clickhouse_driver-0.2.11-cp310-cp310-musllinux_1_2_aarch64.whl; clickhouse_driver-0.2.11-cp310-cp310-musllinux_1_2_ppc64le.whl; clickhouse_driver-0.2.11-cp310-cp310-musllinux_1_2_s390x.whl; clickhouse_driver-0.2.11-cp310-cp310-musllinux_1_2_x86_64.whl; clickhouse_driver-0.2.11-cp310-cp310-win32.whl; clickhouse_driver-0.2.11-cp310-cp310-win_amd64.whl; clickhouse_driver-0.2.11-cp311-cp311-macosx_10_9_x86_64.whl; clickhouse_driver-0.2.11-cp311-cp311-macosx_11_0_arm64.whl; clickhouse_driver-0.2.11-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; clickhouse_driver-0.2.11-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl; clickhouse_driver-0.2.11-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl; clickhouse_driver-0.2.11-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; clickhouse_driver-0.2.11-cp311-cp311-musllinux_1_2_aarch64.whl; clickhouse_driver-0.2.11-cp311-cp311-musllinux_1_2_ppc64le.whl

Keywords: ClickHouse, db, database, cloud, analytics

Tags

More Software Development packages