JDBC 驱动程序

v0.8+

备注

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

从 0.7.x 的变更

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

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

备注

Date 是以无时区方式存储的，而 DateTime 是以带时区方式存储的。如果不小心，可能会导致意想不到的结果。

环境要求

• OpenJDK 版本 >= 8

设置

Maven

Gradle (Kotlin)

Gradle

配置

驱动类: 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 client 提供的 ClickHouse 特定属性。 如果特性不受支持的方法将尽可能返回 SQLFeatureNotSupportedException。其他自定义属性包括：

属性	默认	描述
disable_frameworks_detection	true	禁用针对用户代理的框架检测
jdbc_ignore_unsupported_values	false	抑制 SQLFeatureNotSupportedException
clickhouse.jdbc.v1	false	使用旧的 JDBC 实现而不是新的 JDBC
default_query_settings	null	允许在查询操作中传递默认查询设置

支持的数据类型

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

处理日期、时间和时区

java.sql.Date、java.sql.Time 和 java.sql.Timestamp 可能会使时区计算复杂 - 尽管支持这些类型，您可能希望考虑使用 java.time 包。ZonedDateTime 和 OffsetDateTime 是 java.sql.Timestamp、java.sql.Date 和 java.sql.Time 的两个优秀替代品。

创建连接

提供凭据和设置

简单语句

插入

HikariCP

更多信息

有关更多信息，请参见我们的 GitHub 仓库 和 Java Client 文档。

故障排除

日志记录

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

解决大型插入中的 JDBC 超时

在 ClickHouse 中执行大型插入并且执行时间较长时，您可能会遇到 JDBC 超时错误，例如：

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

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 处理套接字保持活动设置的方式不同，需要额外步骤。请按照以下步骤操作：

1. 在 /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 秒降低）

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

设置这些设置后，您还需要确保您的客户端在套接字上启用了 Keep Alive 选项：