Go操作ClickHouse的三大卡点是连不上、查不到、写不快，根源在于协议选错（tcp/http不匹配）、扫描漏错（未检查rows.Err()）、批量用错（未用PrepareBatch），需严格按配置选协议、补扫描校验、用二进制批处理。
连不上、查不到、写不快——这三个问题占了 Go 操作 ClickHouse 时 90% 的实际卡点。根本原因不是驱动不行，而是协议选错、扫描漏错、批量用错。
tcp:// 还是 http://？协议不对就直接连不上
默认 clickhouse-go v2+ 尝试走 TLS 加密的 Native 协议（tcp://），但很多线上 ClickHouse 实例只开了 tcp_port（9000）且没配证书，或只开了 http_port（8123）但没开压缩。连不上八成是 DSN 前缀和服务器配置不匹配。
- 查服务端配置：
/etc/clickhouse-server/config.xml里确认<tcp_port>9000</tcp_port>是否启用；若只开 HTTP，则必须用http://127.0.0.1:8123 - Native 连接写法：
tcp://127.0.0.1:9000?database=default&secure=false&insecure=true——secure=false和insecure=true必须同时设，否则 TLS 握手失败 - HTTP 连接写法：
http://127.0.0.1:8123?database=default&compress=true——compress=true能省 60%+ 网络带宽，尤其对大结果集 - 别信“localhost”，DNS 解析慢且可能解析到 IPv6；生产环境一律用
127.0.0.1或内网 IP
rows.Scan() 返回空，但 rows.Err() 没检查
ClickHouse 查询返回空结果却不报错，常见于字段顺序错、类型不匹配、NULL 值未处理，而 rows.Scan() 在中途失败后不会自动中断循环，rows.Next() 仍可能返回 false 导致跳过错误。
- 永远在
for rows.Next()循环结束后加：if err := rows.Err(); err != nil { /* 处理 */ }—— 这是唯一能捕获扫描阶段 panic 或类型转换失败的方式 - 拒绝
SELECT *：字段顺序依赖表结构，一改就崩；明确写出字段名，并严格按建表顺序传参，例如SELECT id, name, created→rows.Scan(&id, &name, &created) - 时间字段用
*time.Time或time.Time接收，但注意 ClickHouseDateTime默认是 UTC，Gotime.Now()是本地时区，比较前先统一时区 - 字符串字段优先用
*string，避免NULL触发 panic；数值字段用指针接收也能安全处理 NULL
百万级插入慢？单条 exec 或拼 SQL 都是错的
ClickHouse 是列式引擎，随机小写毫无吞吐可言。单条 stmt.Exec() 或拼接超长 INSERT 语句，会让数据无法按列连续写入，CPU 和网络打满但写入速度卡在几百行/秒。
立即学习“go语言免费学习笔记（深入）”；
- 必须用
conn.PrepareBatch()：它构建的是原生二进制格式批处理，绕过 SQL 解析，直接喂给 ColumnWriter - 每批控制在
10000–50000行之间；太少则 RPC 开销占比高，太多易触发内存 OOM 或超时 - 别在循环里反复调用
conn.PrepareBatch()—— 它本身有连接复用开销；一个 batch 对象可重复.Append()多次，最后.Send() - 需要异步写入时，用
clickhouse.AsyncInsert+ channel 控制背压，而不是自己 goroutine 包一层Exec()
参数化查询怎么写才安全又高效？
ClickHouse 的参数化不是简单占位符替换，它区分标识符（表名、列名）和值（字符串、数组），类型声明必须显式，否则解析失败或类型推导错误。
- Native 风格（推荐）：
SELECT {col:Identifier}, {val:String} FROM {db:Identifier}.{tbl:Identifier}，配合clickhouse.Context(ctx, clickhouse.WithParameters(...)) - 标准库风格：
conn.QueryRow("SELECT {col:Identifier} FROM system.tables WHERE name = {val:String}", clickhouse.Named("col", "name"), clickhouse.Named("val", "test")) - 数组参数要写成
{arr:Array(String)}，值传"['a','b']"字符串；别传 Go slice，驱动不识别 - 别把参数当模板拼接 SQL ——
fmt.Sprintf("SELECT %s FROM %s", col, tbl)仍是 SQL 注入温床，且无法利用 ClickHouse 的 query cache
最常被忽略的其实是连接复用和上下文超时：每个查询都该带 context.WithTimeout(ctx, 30*time.Second)，否则一个慢查询会拖垮整个连接池；而连接池本身必须全局复用，不能每次请求 new 一个 conn。
