Go语言集成ClickHouse关键在“稳写、准读、久跑”：需显式配置协议/认证/时区，百万写入禁用单条INSERT而用Writer或PrepareBatch分批（1万–10万行），查询必设context超时与max_execution_time，Nullable字段须用sql.NullString，扫描后必须检查rows.Err()。
Go 语言集成 ClickHouse 做大数据量实时分析，关键不在“连上”，而在“稳写、准读、久跑”——线上高频出问题的点，集中在认证失败、批量写崩内存、时区错位、空值 panic 和查询卡死这五类。
连接必须显式配协议、认证与时区
多数连不上不是密码错，而是协议和端口不匹配：
- TCP 模式（默认）走 9000 端口，DSN 示例：
tcp://127.0.0.1:9000?database=default&secure=false&compress=false - HTTP 模式（云服务常用）走 8123 端口，URL 中的 user:pass 会被忽略，必须用 Auth 结构体：
Auth: clickhouse.Auth{Username: "default", Password: "xxx"}并设Protocol: clickhouse.HTTP - 连接后立即执行
conn.Exec("SET timezone = 'Asia/Shanghai'")，或 DSN 加&timezone=Asia%2FShanghai，避免 DateTime 解析失败
百万级写入：用流式或分批，别拼 SQL
单条 INSERT 或拼大字符串会吃光内存、触发 GC 飙升甚至 OOM：
- 禁用
db.Query("INSERT ...")或循环调stmt.Exec() - 推荐方案一（高吞吐）：
conn.Writer().Write()+ CSV 流，底层缓冲复用，比 batch 快 3–5 倍 - 推荐方案二（可控性强）：
conn.PrepareBatch("INSERT INTO t")，每批 1 万–10 万行，batch.Reset()复用实例，避免反复 new - 数据来自文件/管道时，直接传
bytes.Reader或io.Pipe，不全量加载到内存
查询务必带 context 超时与服务端限流
ClickHouse 查询不是越快越好，是越可控越好：
立即学习“go语言免费学习笔记（深入）”；
- 每个查询都用带超时的 context：
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) - SQL 中显式加
SETTINGS max_execution_time = 20，防慢查询拖垮 goroutine - WHERE 条件涉及时间字段时，统一转为字符串格式（如
'2026-06-01 12:00:00'）或确保 time.Time 已按 Asia/Shanghai 生成，避免时区错位查不到数据 - 扫描结束后必须检查：
if err := rows.Err(); err != nil { /* 处理 */ }，很多“空结果”其实是中途静默失败
空值与类型：Nullable 字段不能硬接 *string
ClickHouse 的 Nullable(String) 和 Go 的 *string 不兼容，NULL 时直接 panic：
- 必须用
sql.NullString接收，或 v2 驱动中的ch.String -
SELECT *禁止用于生产，字段顺序必须和SELECT a,b,c显式声明一致，否则Scan(&a,&b,&c)错位 - 调用
rows.Columns()校验列名与类型，尤其含COUNT()、GROUP BY或别名时，列序可能变化
