应选用com.clickhouse开头的现代驱动：Java 8–17用0.4.6版，Java 21+或需高级特性选0.7.0+；URL须为jdbc:clickhouse://host:8123/db格式，禁用多余参数；批量写入需开启rewriteBatchedStatements=true并酌情关闭compress。
ClickHouse JDBC驱动选哪个版本才不报 No suitable driver
Java 项目连不上 ClickHouse，八成是驱动没对上——不是随便丢个 clickhouse-jdbc jar 就能用。官方早就不维护旧的 ru.yandex.clickhouse 包了，新项目必须用 com.clickhouse 开头的现代驱动。
- Java 8–17 项目：用
com.clickhouse:clickhouse-jdbc:0.4.6（稳定，兼容性好） - Java 21+ 或需要 Arrow/SSL 高级特性：上
0.7.0+，但注意0.7.0默认禁用 HTTP 压缩，连某些代理会卡住 - Maven 里别同时引新旧两个 groupId，类加载器会冲突，报
No suitable driver而不是连接超时
URL 写错一个字符就进 Connection refused 循环
ClickHouse JDBC URL 格式看着简单，但少写 http://、端口填错、路径多加斜杠，都会让驱动静默 fallback 到 TCP 协议（而默认不启用），最终表现为连不上、无日志、只抛 Connection refused。
- 标准 HTTP 连接写法：
jdbc:clickhouse://localhost:8123/default（8123是 HTTP 端口，不是9000） - 如果用了 Nginx 反代，确保 header 透传
X-ClickHouse-User和X-ClickHouse-Key，否则驱动发的认证头被吃掉，返回 401 却提示连接失败 - URL 末尾不要加
?charset=utf8—— ClickHouse 不认这个参数，驱动会忽略，但容易误导你去查字符集问题
Statement.executeBatch() 批量写入慢得反常？关掉重试和压缩试试
默认配置下，JDBC 驱动会对每个 batch 请求自动重试 + 启用 GZIP，这在高并发写入时反而拖垮吞吐——尤其当 ClickHouse server 的 max_http_timeout 设得偏小，或网络有抖动时，重试逻辑会把延迟放大数倍。
- 写入性能调优关键参数：
jdbc:clickhouse://h:8123/db?rewriteBatchedStatements=true&compress=true&socket_timeout=30000&connect_timeout=5000 -
rewriteBatchedStatements=true必开，它把多个 INSERT 合成一条带 VALUES 列表的语句；不开的话，每个addBatch()都发独立 HTTP 请求 -
compress=false在局域网环境建议关闭——ClickHouse 自身压缩效率更高，客户端压完再解压纯属浪费 CPU
查询结果字段名大小写不一致？别信 setLowerCaseNames(true)
ClickHouse 表字段名默认大小写敏感，但 JDBC 驱动的 setLowerCaseNames(true) 并不能统一 ResultSet 的 getXXX("col") 行为——它只影响 getColumnLabel()，而多数 ORM（如 MyBatis）直接读的是原始列名。
立即学习“Java免费学习笔记（深入）”；
- 最稳做法：建表时全用小写下划线命名（
user_id），查询也显式写小写别名：SELECT user_id AS user_id FROM t - 如果必须兼容大写字段，用
rs.getObject(1)按位置取值，避开名字匹配逻辑 - 驱动
0.6.0+加了useServerTimeZone=false默认值，但如果你的字段含DateTime，不显式设serverTimezone=UTC，Java 侧可能解析错 1 小时
真正麻烦的不是连上，是连上之后字段对不上、时间差一小时、批量写入卡在重试里——这些点藏在文档角落，但每天都在真实发生。
