clickhouse-client

ClickHouse 原生协议客户端

补充说明

clickhouse-client 通过原生协议（默认 9000 端口）连接 ClickHouse，执行查询、导入数据和查看状态。它和 HTTP 接口（8123）是两条不同的路径。

常用示例

clickhouse-client --host ch.example.com --user app --password "$CH_PASSWORD"
clickhouse-client -q 'SELECT version()'
clickhouse-client --query 'SELECT count() FROM app.events'
clickhouse-client --database app --multiquery < init.sql
clickhouse-client -q 'SELECT * FROM app.events LIMIT 5' --format JSONEachRow
clickhouse-client -q 'INSERT INTO app.events FORMAT CSV' < events.csv
clickhouse-client --secure --host ch.example.com --port 9440 --user app
clickhouse-client -q 'SELECT * FROM app.events WHERE dt={dt:Date}' --param_dt=2026-10-18

易错点与排错

• 原生协议端口通常是 9000（TLS 9440），HTTP 是 8123（TLS 8443）；连错端口会超时或协议错误。
• -q 只跑一条查询；多条语句用 --multiquery 或从文件读取。
• FORMAT 要放在整条查询末尾；放在子查询里会语法错误。
• 命令行密码会进历史；优先用配置文件或 CLICKHOUSE_PASSWORD 环境变量。
• ClickHouse 的 ALTER ... UPDATE/DELETE 是异步 mutation，提交成功不代表数据已改完。
• 大结果集不要直接输出到终端；用 --format 配合文件或 LIMIT。
• 分布式表查询可能放大内存和网络开销；先看 system.query_log 和 max_memory_usage。
• TLS、用户名和默认库要一起确认；认证失败和库不存在报错很像。

相关命令

• clickhouse-local — 不启服务端直接查询文件
• clickhouse-server — 服务端