ClickHouse Go 驱动连不上主因是默认启用 TLS 和压缩，需显式设 secure=false、compress=false；批量写入要避免单行 INSERT，改用 stmt.Exec 批量传参（1w–10w 行/批）；读取 Nullable(String) 必须用 sql.NullString 或 ch.String；time.Time 查询需注意时区匹配，建议用字符串格式 WHERE 条件。
用 github.com/ClickHouse/clickhouse-go 连 ClickHouse 时连不上
绝大多数连不上问题不是网络或权限导致的，而是驱动默认启用了压缩和 TLS，但服务端没配好。官方驱动 clickhouse-go v2（即 github.com/ClickHouse/clickhouse-go/v2）默认走 https + lz4 压缩，而本地开发常跑的是裸 http://localhost:8123。
- 显式关掉 TLS：
secure=false，否则会卡在握手阶段，日志里可能只报context deadline exceeded - 禁用压缩避免协议不匹配：
compress=false；如果服务端开了 LZ4 而客户端没配，会收到Code: 287. DB::Exception: Unknown compression method - 连接字符串示例：
tcp://127.0.0.1:9000?database=default&secure=false&compress=false（注意：HTTP 接口是 8123，TCP 是 9000，驱动默认走 TCP）
批量写入 ClickHouse 千万级数据慢得像卡住
Go 客户端默认单条 INSERT 发一次请求，网络往返开销压垮吞吐。ClickHouse 的设计哲学是“大块写入”，INSERT 语句本身不慢，慢在频繁建连接、序列化、解析 SQL 字符串。
- 必须用
stmt.Exec()批量传参，而不是拼 SQL 字符串——后者容易触发 SQL 注入检查且无法复用执行计划 - 每批控制在 1w–10w 行之间：太小（如 100 行）仍频繁交互；太大（如 100w 行）可能触发内存 OOM 或服务端
max_insert_block_size限制 - 开启
async_insert=true参数可缓解阻塞，但仅适用于非关键路径，因为异步插入失败不会立即反馈错误 - 别用
database/sql标准库封装层做高频写入——它加了额外事务抽象和 prepare 缓存，反而拖慢原生批量能力
Scan() 读取 string 类型字段时 panic: “cannot scan into *string”
这是 clickhouse-go 对空值（NULL）处理的典型陷阱。ClickHouse 的 String 类型允许为 NULL，但 Go 的 *string 不等于 ClickHouse 的 Nullable(String) —— 后者在驱动里对应的是 sql.NullString 或自定义的 ch.String（v2 驱动中）。
- 查出来的列如果是
Nullable(String)，必须用sql.NullString接收，不能直接用*string - 如果确定字段非空，建表时就该定义为
String（无 Nullable），而非依赖应用层判空 - v2 驱动支持
ch.String类型，比sql.NullString更贴合 ClickHouse 语义，但需手动 importgithub.com/ClickHouse/clickhouse-go/v2/lib/columns - 错误示例：
var s *string; row.Scan(&s)→ panic；正确写法：var s sql.NullString; row.Scan(&s)
WHERE 条件里用 time.Time 查询日期范围结果为空
ClickHouse 的日期类型（Date / DateTime）和 Go 的 time.Time 时区隐含逻辑不一致。驱动默认把 time.Time 当作 UTC 时间写入，但如果你的表字段是 Date（无时区），或者服务端时区设为 Asia/Shanghai，就会出现“时间对得上却查不到”的情况。
立即学习“go语言免费学习笔记（深入）”；
- 查
Date类型字段时，统一用time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)构造，再让驱动自动截断为日期 - 查
DateTime字段时，确保传入的time.Time的Location和 ClickHouse server 的timezone配置一致（可通过SELECT timezone()查看） - 最稳方案：WHERE 中不用
time.Time直接比较，改用字符串格式，如WHERE event_date >= '2024-01-01'，驱动能准确映射 - 注意：
time.Now().AddDate(0,0,-7)返回的时间带本地时区，若未显式转 UTC 或上海时区，很可能跨天
ClickHouse 在 Go 里不是“换个数据库驱动就行”的事——它的列式存储、类型系统、NULL 处理、时区模型都和传统关系库不同。最容易被忽略的是：所有优化都建立在“你清楚自己建的表是什么类型、服务端配了什么时区、驱动默认开了哪些协议特性”之上。少一个环节对不上，就变成调半天才发现是 secure=true 在连本地 HTTP。
