Go语言操作ClickHouse教程

本文深入解析了Go语言连接和操作ClickHouse的四大核心痛点：连接失败多因驱动默认启用TLS和LZ4压缩，而本地部署常为裸TCP/HTTP，必须显式配置`secure=false&compress=false`；INSERT性能瓶颈源于逐行执行，正确做法是使用`PrepareBatch`按列批量攒批（1000–10000行/批）并调用`Send`；处理`Nullable`字段时不可直接用`*string`，须改用`sql.NullString`或`ch.String`避免panic；分布式查询结果不一致实为分片未全局聚合所致，需在SQL中添加`SETTINGS distributed_group_by_no_merge = 0`等查询级设置强制服务端合并——这些看似隐蔽的细节，恰恰是生产环境中最易踩坑、又最难定位的关键所在。

连不上 ClickHouse？大概率是 secure 和 compress 没关对

绝大多数 context deadline exceeded 或直接卡住，根本不是网络不通，而是驱动默认走 TLS + LZ4 压缩，但本地 ClickHouse 通常跑在裸 http://localhost:8123 或 tcp://localhost:9000 上，没配证书也没开压缩。

• 用 TCP 协议（端口 9000）时，连接串必须显式加 secure=false&compress=false，例如：tcp://127.0.0.1:9000?database=default&secure=false&compress=false
• HTTP 接口（端口 8123）不被 clickhouse-go/v2 原生支持——别试；v2 驱动只认 TCP
• 如果服务端开了 LZ4 而客户端没配 compress=true，会报错：Code: 287. DB::Exception: Unknown compression method

INSERT 慢得像卡死？别用 db.Exec() 拼单行 SQL

ClickHouse 不是 MySQL，单条 INSERT 触发一次小合并（minor merge），10 万行逐条插可能要几十秒；真正快的写法是列式批量攒批发送。

• 必须用 conn.PrepareBatch() 获取 Batch 对象，不是 conn.Prepare()
• batch.Append() 只是内存攒数据，不发包；攒够再调 batch.Send()
• 每批控制在 1000–10000 行：太少仍频繁交互，太大易 OOM 或触发服务端 max_insert_block_size
• 别传 []struct{}，要按列组织：比如两列 id, name，就得传 []int64 和 []string 两个切片

查出来字段是 Nullable(String)，Scan(&s) 直接 panic？

Go 的 *string ≠ ClickHouse 的 Nullable(String)。驱动不会自动帮你判空，一扫就崩是常态。

• 必须用 sql.NullString 接收，或 v2 驱动推荐的 ch.String（需 import "github.com/ClickHouse/clickhouse-go/v2/lib/columns"）
• 如果确定字段非空，建表时就该定义为 String，而不是依赖应用层处理 NULL
• Rows.Scan() 不校验列数，也不自动分配切片容量——务必先调 rows.Columns() 看字段名和类型，尤其用了别名或聚合函数时

GROUP BY 结果不准、ORDER BY 失效？不是 Go 客户端问题

这是 ClickHouse 分布式行为导致的“服务端未最终合并”，Go client 拿到的是各分片原始结果，不是全局聚合后结果。

• 在 SQL 开头加 SETTINGS distributed_group_by_no_merge = 0，强制服务端做最终 merge
• 类似还有 optimize_sorting_by_input = 0，用于修复 ORDER BY 在分布式 JOIN 下失效
• 这些 setting 是查询级的，不影响服务端全局配置，安全可加

最麻烦的从来不是语法怎么写，而是 NULL 怎么接、压缩怎么关、批量怎么攒、分布式结果怎么合——每个点都静默失败，不报错也不给提示，全靠经验踩坑填平。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~