go集成clickhouse核心难点是写稳、读准、跑久：需显式配置auth与protocol防401/dial timeout；批量写控1万–10万行并复用batch防oom；时区统一设asia/shanghai，nullable字段用sql.nullstring；查询必设context超时与max_execution_time。
Go 语言集成 ClickHouse 做大数据分析，核心难点不在“连得上”，而在“写得稳、读得准、跑得久”——多数线上事故都出在认证配置错、批量写崩内存、时区不一致或空值 panic 上。
clickhouse-go 连接 401 或 dial timeout 怎么办
HTTP 模式下 http://user:pass@host:8123 这种 DSN 写法完全无效，驱动会忽略 URL 中的凭据，直接走默认 TCP 协议去连 8123 端口，结果就是 dial timeout；或者 Auth 字段没填，报 failed to connect 却不提 401。
- 必须显式设置
Auth: clickhouse.Auth{Username: "default", Password: "xxx"} - 必须指定
Protocol: clickhouse.HTTP，否则默认走 TCP 协议 - 若服务端只开 9000（TCP），就别用 HTTP 模式，改用
tcp://host:9000?secure=false&compress=false - 云服务（如 ByteHouse）通常只开放 8123，必须走 HTTP + Auth 结构体
INSERT 百万行 OOM 或 CPU 飙高
用 batch.Append() 塞几千个 struct 后调 batch.Send()，底层仍会把整批序列化成一个大 CSV 字符串，GC 压力陡增，容易触发 Go runtime OOM 或 ClickHouse 服务端 max_insert_block_size 限流。
- 每批控制在 1 万–10 万行之间，别设成 50 万
- 避免反复 new batch，用
batch.Reset()复用实例 - 真要流式写入（比如从 Kafka 消费），改用
conn.Insert("INSERT INTO ...", reader)配bytes.Reader或管道 - 别用
database/sql封装层做高频写入，prepare 缓存和事务抽象反而拖慢原生吞吐
Scan() 读 time.Time 或 string 字段 panic
查出来的 DateTime 字段变成零值或直接 panic: cannot parse time，大概率是服务端时区（如 Asia/Shanghai）和客户端没对齐；Nullable(String) 字段用 *string 接，就会在 NULL 时 panic。
- 连接后立刻执行
conn.Exec("SET timezone = 'Asia/Shanghai'")，或 DSN 加&timezone=Asia%2FShanghai -
Nullable(String)必须用sql.NullString或 v2 驱动的ch.String接收 - 字段顺序必须和
SELECT显式列出的顺序严格一致，别依赖SELECT * - 扫描循环结束后务必检查
if err := rows.Err(); err != nil，很多“空结果”其实是扫描中途静默失败
查询慢、结果不准、context 超时频繁
ClickHouse 查询不是越快越好，而是越可控越好。默认 context 没设超时，max_execution_time 又没配，一个慢查询可能卡住整个 goroutine；WHERE 条件里用 time.Now() 和 DateTime 字段比，时区不统一就查不到数据。
- 每个查询都带独立
context.WithTimeout(ctx, 30*time.Second)，别复用长生命周期 context - 显式设置
max_execution_time：在 DSN 加&max_execution_time=60，或 query 前执行SET max_execution_time = 60 - 时间比较一律转成字符串（如
WHERE created > '2026-04-24 00:00:00'）或用toDateTime()函数对齐时区 - GROUP BY 必须显式
AS别名，且Scan()变量顺序要跟 SELECT 字段顺序一致
最常被跳过的其实是时区对齐和空值类型匹配——这两点不提前确认，后面所有优化都白搭，而且问题往往延迟暴露，在压测或上线后才集中爆发。
