ClickHouse Go驱动配置四大关键：协议端口需显式指定、批量写必须分批、Nullable字段用sql.NullString、查询需双超时防护；否则易连不上、写崩、读错、卡死。
连不上、写崩、读错、卡死——不是 ClickHouse 不行，是 Go 驱动配置没对齐。核心就四件事：协议端口必须显式指定、批量写必须分批、Nullable 字段必须用 sql.NullString、查询必须双超时防护。
连接失败？先查协议和端口是否匹配
90% 的“连不上”不是密码错，而是驱动默认走 TCP（9000 端口），但服务端只开了 HTTP（8123）或反之。驱动不会自动探测协议，必须人工指定。
- 若 ClickHouse 监听
9000（Native 协议）：DSN 用tcp://127.0.0.1:9000?database=default&secure=false&compress=false，Options.Protocol可省略（默认 Native） - 若只开放
8123（HTTP 协议）：DSN 改为http://127.0.0.1:8123?database=default&compress=true，且必须设Protocol: clickhouse.HTTP，Auth结构体传用户名密码——URL 里的user:pass在 HTTP 模式下会被忽略 - 云服务（如 ClickHouse Cloud）常只开 TLS Native（9440）或 HTTP（8123），务必以控制台给出的连接命令为准，别凭经验硬套
百万行 INSERT OOM？别拼 SQL，用 PrepareBatch 控制批大小
循环调 stmt.Exec() 或拼大字符串 INSERT，会把整批数据塞进内存，GC 崩溃、ClickHouse 触发 max_insert_block_size 限流，甚至被 kill。
- 禁用：
db.Query("INSERT ...")、for range { stmt.Exec(...) } - 改用：
batch, err := conn.PrepareBatch(ctx, "INSERT INTO t(a,b) VALUES (?,?)")，每批塞10000–100000行，batch.Send()后调batch.Reset()复用实例 - 文件/管道数据源：直接传
bytes.Reader或io.Pipe给conn.Writer().Write()，底层缓冲复用，比 batch 快 3–5 倍
Scan() panic 或时间字段错乱？Nullable 和时区必须显式处理
sql.NullString 不是“可选优化”，是防止 panic 的刚需；time.Time 解析失败，八成是服务端和客户端时区没对齐。
立即学习“go语言免费学习笔记（深入）”；
- 连接后立刻执行：
conn.Exec("SET timezone = 'Asia/Shanghai'")，或 DSN 加&timezone=Asia%2FShanghai -
Nullable(String)字段必须用sql.NullString或 v2 驱动的ch.String接收，用*string必 panic - 查询必须显式列字段：
SELECT a,b,c FROM t，且rows.Scan(&a,&b,&c)顺序严格一致；禁用SELECT * - 扫描循环结束后必须检查：
if err := rows.Err(); err != nil——很多“空结果”其实是中途静默失败
查询卡死或超时频繁？context.WithTimeout 和 SETTINGS max_execution_time 缺一不可
ClickHouse 查询不是越快越好，是越可控越好。单靠 Go 层超时不够，服务端不设限，慢查询照样拖垮 goroutine。
- 每个查询都带 context：
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) - SQL 中显式加限流：
SELECT ... SETTINGS max_execution_time = 20 - HTTP 模式下流式读取（百万行日志）：必须设
stream=1&format=JSONEachRow，用json.Decoder逐行解码，禁用json.Unmarshal([]byte)全量加载 - DateTime64 查询条件必须用 UTC 构造：
t := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)，再转成 ClickHouse 能识别的格式，别依赖time.Now().UTC().Format(...)—— 时区转换可能丢精度
真正难的不是写几行代码连上，而是让百万写入不崩、空值不 panic、时区不错位、慢查询不拖垮整个服务——这些细节全在配置里，漏一个，线上就出事。
