在Java应用中接入ClickHouse做分析查询，核心环节是JDBC驱动的集成与运行环境搭建。ClickHouse作为列式存储数据库，官方维护了独立的JDBC客户端，它并不依赖MySQL或PostgreSQL协议，而是基于HTTP或原生TCP实现。理解驱动架构，是后续写出稳定数据管道的前提。
依赖引入与驱动类型选择
ClickHouse的JDBC驱动在Maven中央仓库中以ru.yandex.clickhouse和较新的com.clickhouse两组坐标存在。旧版驱动包名以ru.yandex.clickhouse.jdbc开头，使用HTTP接口，连接稳定但性能一般；新版驱动拆分为clickhouse-jdbc与clickhouse-client，支持原生协议，吞吐更高。选择时需确认服务端版本，ClickHouse 21以后建议用新版驱动避免兼容警告。
在pom.xml中引入依赖时，不要同时混用两套驱动，否则类加载器可能加载到错误实现。以下示例展示新版驱动的基础引入方式，其中排除了传递的旧日志组件以减少冲突。
<dependency>
<groupId>com.clickhouse</groupId>
<artifactId>clickhouse-jdbc</artifactId>
<version>0.6.0</version>
<exclusions>
<exclusion>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
</exclusion>
</exclusions>
</dependency>
驱动类型方面，连接串前缀决定通信方式。jdbc:clickhouse:http://走HTTP端口8123，防火墙友好；jdbc:clickhouse://走9000原生端口，要求服务端开启native协议。开发环境用HTTP更易排查，生产集群若网络可控可切原生端口降低延迟。
连接池配置与超时参数
直接用DriverManager.getConnection创建连接不适合高并发场景，连接建立和销毁开销会拖慢分析任务。HikariCP是目前最轻量的池化方案，将其与ClickHouse JDBC结合，需要设置合理的maximumPoolSize与connectionTimeout。由于列式查询常返回大结果集，建议把maxLifetime设短于服务端keep_alive周期，防止拿到僵死连接。
下面代码演示Spring Boot外独立使用HikariCP管理ClickHouse连接的写法。注意driverClassName必须显式指定，因为JDBC 4自动发现机制在某些OSGi或模块化环境下会失效。
import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;
public class ChPool {
public static void main(String[] args) throws Exception {
HikariConfig cfg = new HikariConfig();
cfg.setDriverClassName("com.clickhouse.jdbc.ClickHouseDriver");
cfg.setJdbcUrl("jdbc:clickhouse:http://127.0.0.1:8123/default");
cfg.setUsername("default");
cfg.setPassword("");
cfg.setMaximumPoolSize(10);
cfg.setConnectionTimeout(30000);
cfg.setIdleTimeout(600000);
HikariDataSource ds = new HikariDataSource(cfg);
try (Connection conn = ds.getConnection();
Statement st = conn.createStatement();
ResultSet rs = st.executeQuery("SELECT count() FROM system.tables")) {
if (rs.next()) {
System.out.println("tables:" + rs.getLong(1));
}
}
ds.close();
}
}
超时方面，ClickHouse查询可能因数据量产生长耗时，JDBC层需通过socket_timeout参数保护。该参数追加在连接串后，如?socket_timeout=60000。若未设置，网络抖动时线程会无限等待，进而占满池内连接。同时，服务端max_execution_time也应配套调整，避免客户端等待但服务端已终止的错位。
批量写入与本地环境验证
分析数据库环境搭建完毕后，通常用程序灌入样本数据验证链路。ClickHouse JDBC的PreparedStatement支持addBatch，但默认不在服务端做批聚合，若一次添加数十万条而不设reWriteBatchedInserts类参数，客户端内存会陡增。正确做法是在连接串开启batch_size限制，并分批提交。
以下示例展示从CSV内存列表向test_java表批量写入，每五百行提交一次，避免单次堆外缓冲溢出。建表语句采用MergeTree引擎，这是本地分析环境最常用的表类型。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.util.ArrayList;
import java.util.List;
public class BatchInsert {
public static void main(String[] args) throws Exception {
String url = "jdbc:clickhouse:http://127.0.0.1:8123/default?batch_size=500";
try (Connection conn = DriverManager.getConnection(url, "default", "")) {
conn.createStatement().execute(
"CREATE TABLE IF NOT EXISTS test_java (id UInt32, name String) ENGINE = MergeTree ORDER BY id");
List<String[]> rows = new ArrayList<>();
for (int i = 0; i < 2000; i++) {
rows.add(new String[]{String.valueOf(i), "u" + i});
}
String sql = "INSERT INTO test_java (id, name) VALUES (?, ?)";
try (PreparedStatement ps = conn.prepareStatement(sql)) {
int cnt = 0;
for (String[] r : rows) {
ps.setInt(1, Integer.parseInt(r[0]));
ps.setString(2, r[1]);
ps.addBatch();
if (++cnt % 500 == 0) {
ps.executeBatch();
}
}
ps.executeBatch();
}
}
}
}
本地验证时，可用Docker快速拉起单节点实例：docker run -d --name ch -p 8123:8123 -p 9000:9000 clickhouse/clickhouse-server。待健康检测通过后，运行上述Java代码即可确认驱动集成无误。若报错No suitable driver，优先检查依赖是否真正打入运行包，而非仅编译期存在。环境通联后，便可在Java分析服务中放心使用ClickHouse承担聚合查询与明细落盘。
ClickHouseJDBC_driverJava修改时间：2026-08-16 23:16:34