JDBC 驱动程序

v0.8+

备注

clickhouse-jdbc 实现了使用最新 Java 客户端的标准 JDBC 接口。如果性能/直接访问至关重要，我们建议直接使用最新的 Java 客户端。

从 0.7.x 的变化

在 0.8 中，我们尝试使驱动程序更严格地遵循 JDBC 规范，因此有一些可能会影响您的移除功能：

旧特性	备注
事务支持	驱动程序的早期版本仅模拟事务支持，这可能会产生意外结果。
响应列重命名	`ResultSet` 是可变的 - 出于效率考虑，现在它们是只读的
多语句 SQL	多语句支持仅仅是模拟，现在严格遵循 1:1
命名参数	不属于 JDBC 规范
基于流的 `PreparedStatement`	驱动程序的早期版本允许非 JDBC 使用 `PreparedStatement` - 如果您希望使用此类选项，我们建议查看 Java 客户端及其示例。

备注

Date 不带时区存储，而 DateTime 带时区存储。如果不小心，这可能导致意外结果。

环境要求

OpenJDK 版本 >= 8

设置

Maven
Gradle (Kotlin)
Gradle

<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.9.1</version>
    <classifier>shaded-all</classifier>
</dependency>

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation("com.clickhouse:clickhouse-jdbc:0.9.1:shaded-all")

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation 'com.clickhouse:clickhouse-jdbc:0.9.1:shaded-all'

配置

驱动类: com.clickhouse.jdbc.ClickHouseDriver

URL 语法: jdbc:(ch|clickhouse)[:<protocol>]://endpoint1[,endpoint2,...][/<database>][?param1=value1&param2=value2][#tag1,tag2,...]，例如：

jdbc:clickhouse:http://localhost:8123
jdbc:clickhouse:https://localhost:8443?ssl=true

连接属性:

除了标准 JDBC 属性外，驱动程序还支持底层 java 客户端提供的 ClickHouse 特定属性。如果不支持某功能，方法将尽可能返回 SQLFeatureNotSupportedException。其他自定义属性包括：

属性	默认	描述
`disable_frameworks_detection`	`true`	禁用 User-Agent 的框架检测
`jdbc_ignore_unsupported_values`	`false`	抑制 `SQLFeatureNotSupportedException`
`clickhouse.jdbc.v1`	`false`	使用旧的 JDBC 实现而不是新的 JDBC
`default_query_settings`	`null`	允许在查询操作中传递默认查询设置
`jdbc_resultset_auto_close`	`true`	当 `Statement` 被关闭时自动关闭 `ResultSet`
`beta.row_binary_for_simple_insert`	`false`	对基于 `RowBinary` 写入器的 `PreparedStatement` 实现。仅适用于 `INSERT INTO ... VALUES` 查询。

支持的数据类型

JDBC 驱动程序支持与底层 java 客户端相同的数据格式。

处理日期、时间和时区

java.sql.Date、java.sql.Time 和 java.sql.Timestamp 可能会使时区计算变得复杂 - 尽管它们当然是支持的，您可能希望考虑使用 java.time 包。ZonedDateTime 和 OffsetDateTime 都是 java.sql.Timestamp、java.sql.Date 和 java.sql.Time 的很好的替代品。

创建连接

String url = "jdbc:ch://my-server:8123/system";

Properties properties = new Properties();
DataSource dataSource = new DataSource(url, properties);//DataSource or DriverManager are the main entry points
try (Connection conn = dataSource.getConnection()) {
... // do something with the connection

提供凭据和设置

String url = "jdbc:ch://localhost:8123?jdbc_ignore_unsupported_values=true&socket_timeout=10";

Properties info = new Properties();
info.put("user", "default");
info.put("password", "password");
info.put("database", "some_db");

//Creating a connection with DataSource
DataSource dataSource = new DataSource(url, info);
try (Connection conn = dataSource.getConnection()) {
... // do something with the connection
}

//Alternate approach using the DriverManager
try (Connection conn = DriverManager.getConnection(url, info)) {
... // do something with the connection
}

简单语句


try (Connection conn = dataSource.getConnection(...);
    Statement stmt = conn.createStatement()) {
    ResultSet rs = stmt.executeQuery("select * from numbers(50000)");
    while(rs.next()) {
        // ...
    }
}

插入

try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (?, ?)")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.addBatch();
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

`HikariCP`

// connection pooling won't help much in terms of performance,
// because the underlying implementation has its own pool.
// for example: HttpURLConnection has a pool for sockets
HikariConfig poolConfig = new HikariConfig();
poolConfig.setConnectionTimeout(5000L);
poolConfig.setMaximumPoolSize(20);
poolConfig.setMaxLifetime(300_000L);
poolConfig.setDataSource(new ClickHouseDataSource(url, properties));

try (HikariDataSource ds = new HikariDataSource(poolConfig);
     Connection conn = ds.getConnection();
     Statement s = conn.createStatement();
     ResultSet rs = s.executeQuery("SELECT * FROM system.numbers LIMIT 3")) {
    while (rs.next()) {
        // handle row
        log.info("Integer: {}, String: {}", rs.getInt(1), rs.getString(1));//Same column but different types
    }
}

故障排除

日志记录

驱动程序使用 slf4j 进行日志记录，并将使用 classpath 上第一个可用的实现。

解决大型插入的 JDBC 超时

在 ClickHouse 执行长时间的大型插入时，您可能会遇到像以下的 JDBC 超时错误：

Caused by: java.sql.SQLException: Read timed out, server myHostname [uri=https://hostname.aws.clickhouse.cloud:8443]

这些错误可能会中断数据插入过程并影响系统稳定性。为了解决此问题，您可能需要调整客户端操作系统中的一些超时设置。

Mac OS

在 Mac OS 上，可以调整以下设置来解决问题：

net.inet.tcp.keepidle: 60000
net.inet.tcp.keepintvl: 45000
net.inet.tcp.keepinit: 45000
net.inet.tcp.keepcnt: 8
net.inet.tcp.always_keepalive: 1

Linux

在 Linux 上，仅仅设置等效的参数可能无法解决问题。由于 Linux 处理套接字保持活动设置的方式不同，因此需要额外的步骤。请按照以下步骤操作：

在 /etc/sysctl.conf 或相关配置文件中调整以下 Linux 内核参数：

net.inet.tcp.keepidle: 60000
net.inet.tcp.keepintvl: 45000
net.inet.tcp.keepinit: 45000
net.inet.tcp.keepcnt: 8
net.inet.tcp.always_keepalive: 1
net.ipv4.tcp_keepalive_intvl: 75
net.ipv4.tcp_keepalive_probes: 9
net.ipv4.tcp_keepalive_time: 60 (您可能考虑将此值从默认的 300 秒降低)

修改内核参数后，通过运行以下命令应用更改：

sudo sysctl -p

设置这些设置后，您需要确保客户端在套接字上启用保持活动选项：

properties.setProperty("socket_keepalive", "true");

从 0.7.x 的变化​

环境要求​

设置​

配置​

支持的数据类型​

处理日期、时间和时区​

创建连接​

提供凭据和设置​

简单语句​

插入​

HikariCP​

更多信息​

故障排除​

日志记录​

解决大型插入的 JDBC 超时​

Mac OS​

Linux​