clickhouse-driver：ClickHouse 的 Python 原生驱动

mymarilyn/clickhouse-driver 是 ClickHouse 的 Python 驱动，基于原生 TCP 协议实现。该项目当前收获了 1,298 个 Star。

ClickHouse 是高性能列式数据库，在数据分析场景中使用广泛。HTTP 接口虽然通用，但在某些场景下存在限制。该驱动直接通过 TCP 协议与 ClickHouse 服务端通信，支持更完整的功能集和更优的交互效率。

该驱动的类型系统覆盖较全，基本涵盖了 ClickHouse 的核心数据类型：

• 数值类型：Float32 / Float64、[U]Int8 / 16 / 32 / 64 / 128 / 256、Decimal
• 日期时间类型：Date / Date32 / DateTime / DateTime64，支持时区参数
• 字符串类型：String / FixedString
• 复合类型：Array(T)、Tuple(T1, T2, …)、Nested、Map(key, value)
• 特殊类型：Enum8 / Enum16、Nullable(T)、Bool、UUID、IPv4 / IPv6、LowCardinality(T)、SimpleAggregateFunction(F, T)

除基础类型外，项目还提供了一些实用的运行时功能。外部数据查询处理允许在查询中注入外部数据集。查询设置支持动态调整执行参数。数据传输支持压缩和 TLS 加密。查询过程中可获取进度信息，结果以块为单位流式返回，内存占用较低。这些功能对大规模数据查询场景比较实用。

项目还具备读取查询 profile 信息的能力，方便排查性能问题。服务端日志可直接在客户端接收。多主机配置支持故障转移，某个节点不可用时会自动切换到备用节点。

项目兼容 Python DB API 2.0 规范，对习惯标准数据库接口的开发者友好。同时提供可选的 NumPy 数组支持，方便与数据分析工具链集成。异步版本 aioch 在另一个仓库维护。

安装

通过 pip 直接安装：

pip install clickhouse-driver

使用示例

1、Pure Client

直接创建 Client 实例，调用 execute 方法执行 SQL：

from clickhouse_driver import Client

client = Client('localhost')
client.execute('SHOW TABLES')
client.execute('CREATE TABLE test (x Int32) ENGINE = Memory')
client.execute('INSERT INTO test (x) VALUES', [{'x': 100}])
client.execute('SELECT sum(x) FROM test')

支持参数化查询，通过字典传入变量值：

client.execute(
    'INSERT INTO test (x) SELECT * FROM system.numbers LIMIT %(limit)s',
    {'limit': 3}
)

2、DB API

通过 connect 建立连接，使用 cursor 执行操作：

from clickhouse_driver import connect

conn = connect('clickhouse://localhost')
cursor = conn.cursor()
cursor.execute('SHOW TABLES')
cursor.fetchall()
cursor.executemany('INSERT INTO test (x) VALUES', [{'x': 100}])
cursor.execute('SELECT sum(x) FROM test')
cursor.fetchall()

完整文档见 clickhouse-driver.readthedocs.io。

FROM test’)
cursor.fetchall()

完整文档见 clickhouse-driver.readthedocs.io。