JDBC 驱动

v0.8+

注意

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

环境要求

• OpenJDK 8 或更高版本

设置

Maven

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

Gradle（Kotlin）

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

Gradle

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

配置

驱动程序类: com.clickhouse.jdbc.ClickHouseDriver

注意

com.clickhouse.jdbc.ClickHouseDriver 是新旧 JDBC 实现的外观类,默认使用新的 JDBC 实现。 如需使用旧的 JDBC 实现,可在连接属性中将 clickhouse.jdbc.v1 属性设置为 true。

com.clickhouse.jdbc.Driver 是新版 JDBC 实现。 com.clickhouse.jdbc.DriverV1 是旧版 JDBC 实现。

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

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

关于 URL 语法,有以下几点需要注意:

• URL 中只允许包含一个 endpoint
• 当所用协议不是默认的 'HTTP' 时，应显式指定协议
• 当端口不是默认值 '8123' 时，必须显式指定端口。
• 驱动程序不会根据端口推断协议，你需要显式指定协议。
• 如果已指定协议，则无需设置 ssl 参数。

连接属性

主要配置参数在 java client 中定义。这些参数应按原样传递给驱动程序。驱动程序还有一些自有属性,它们不属于客户端配置的一部分,具体列举如下。

驱动属性:

属性	默认值	描述
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_resultset_auto_close	true	当关闭 Statement 时自动关闭 ResultSet
jdbc_use_max_result_rows	false	启用后，将使用服务器属性 max_result_rows 来限制查询返回的行数；启用该选项时，会覆盖用户配置的溢出模式。有关详细信息，请参见 JavaDoc。
jdbc_sql_parser	JAVACC	配置要使用的 SQL 解析器类型。可选值为：ANTLR4、ANTLR4_PARAMS_PARSER、JAVACC。

服务器设置

所有服务器设置都应以 clickhouse_setting_ 为前缀(与客户端配置相同)。

Properties config = new Properties();
config.setProperty("user", "default");
config.setProperty("password", getPassword());

// set server setting
config.put(ClientConfigProperties.serverSetting("allow_experimental_time_time64_type"), "1");

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", config);

配置示例:

Properties properties = new Properties();
properties.setProperty("user", "default");
properties.setProperty("password", getPassword());
properties.setProperty("client_name", "my-app-01"); // when http protocol is used it will be `http_user_agent` in the query log but not `client_name`.

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);

这等同于以下 JDBC URL:

jdbc:ch:http://localhost:8123/?user=default&password=password&client_name=my-app-01 
// credentials shoud be passed in `Properties`. Here it is just for example.

注意:无需对 JDBC URL 或属性进行 URL 编码,系统将自动进行编码。

支持的数据类型

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

JDBC 类型映射

以下映射适用于:

• ResultSet#getObject(columnIndex) 方法将返回相应 Java 类的对象。（Int8 -> java.lang.Byte，Int16 -> java.lang.Short 等）
• ResultSetMetaData#getColumnType(columnIndex) 方法将返回对应的 JDBC 类型（Int8 -> java.lang.Byte，Int16 -> java.lang.Short 等）。

有几种方法可以更改映射:

• ResultSet#getObject(columnIndex, class) - 该方法会尝试将值转换为指定的 class 类型。此类转换存在一些限制。详情请参阅各节说明。

数值类型

ClickHouse 类型	JDBC 类型	Java 类
Int8	TINYINT	java.lang.Byte
Int16	SMALLINT	java.lang.Short
Int32	INTEGER	java.lang.Integer
Int64	BIGINT	java.lang.Long
Int128	OTHER	java.math.BigInteger
Int256	OTHER	java.math.BigInteger
UInt8	OTHER	java.lang.Short
UInt16	OTHER	java.lang.Integer
UInt32	OTHER	java.lang.Long
UInt64	OTHER	java.math.BigInteger
UInt128	OTHER	java.math.BigInteger
UInt256	OTHER	java.math.BigInteger
Float32	REAL	java.lang.Float
Float64	DOUBLE	java.lang.Double
Decimal32	DECIMAL	java.math.BigDecimal
Decimal64	DECIMAL	java.math.BigDecimal
Decimal128	DECIMAL	java.math.BigDecimal
Decimal256	DECIMAL	java.math.BigDecimal
Bool	BOOLEAN	java.lang.Boolean

• 数值类型之间可以相互转换。因此，可以将 Int8 读取为 Float64，反之亦然：
  • rs.getObject(1, Float64.class) 将返回 Int8 列的 Float64 值。
  • rs.getLong(1) 将返回 Int8 列的 Long 值。
  • rs.getByte(1) 可以返回 Int16 列的 Byte 值，如果该值在 Byte 的表示范围内。
• 由于存在数据损坏风险，不建议将宽类型转换为窄类型。
• Bool 类型也可以作为数值使用。
• 所有数值类型都可以读取为 java.lang.String。

字符串类型

ClickHouse 类型	JDBC 类型	Java 类
String	VARCHAR	java.lang.String
FixedString	VARCHAR	java.lang.String

• String 只能读取为 java.lang.String 或 byte[]。
• FixedString 会按原样读取，并用零字节填充到该列的长度。(例如，将 'John' 存储为 FixedString(10) 时，读取结果为 'John\0\0\0\0\0\0\0\0\0'。)

枚举类型

ClickHouse 类型	JDBC 类型	Java 类
Enum8	OTHER	java.lang.String
Enum16	OTHER	java.lang.String

• Enum8 和 Enum16 默认映射为 java.lang.String。
• 枚举值可以通过指定的 getter 方法或 getObject(columnIndex, Integer.class) 方法读取为数值。
• Enum16 在内部映射为 short 类型，而 Enum8 映射为 byte 类型。应避免将 Enum16 以 byte 形式读取，因为存在数据损坏的风险。
• 可以在 PreparedStatement 中将 Enum 值设置为字符串值或数值。

日期/时间类型

ClickHouse 类型	JDBC 类型	Java 类
Date	DATE	java.sql.Date
Date32	DATE	java.sql.Date
DateTime	TIMESTAMP	java.sql.Timestamp
DateTime64	TIMESTAMP	java.sql.Timestamp
Time	TIME	java.sql.Time
Time64	TIME	java.sql.Time

• 日期/时间类型会映射为 java.sql 类型,以便更好地兼容 JDBC。不过,仍然可以通过调用 ResultSet#getObject(columnIndex, Class<T>),并将相应的类作为第二个参数,获取 java.time.LocalDate、java.time.LocalDateTime、java.time.LocalTime。
  • rs.getObject(1, java.time.LocalDate.class) 将返回 Date 列中对应的 java.time.LocalDate 值。
  • rs.getObject(1, java.time.LocalDateTime.class) 将返回 DateTime 列中对应的 java.time.LocalDateTime 值。
  • rs.getObject(1, java.time.LocalTime.class) 将返回 Time 列中对应的 java.time.LocalTime 值。
• Date、Date32、Time、Time64 不受服务器时区影响。
• DateTime、DateTime64 会受到服务器时区或会话时区的影响。
• 可以通过 getObject(colIndex, ZonedDateTime.class) 将 DateTime 和 DateTime64 获取为 ZonedDateTime。

采集类型

ClickHouse 类型	JDBC 类型	Java 类
Array	ARRAY	java.sql.Array
Tuple	OTHER	Object[]
Map	JAVA_OBJECT	java.util.Map

• Array 默认会映射为 java.sql.Array，以保证与 JDBC 的兼容性。同时还能提供有关返回数组值的更多信息，有利于进行类型推断。
• Array 实现了 getResultSet() 方法，用于返回内容与原始数组相同的 java.sql.ResultSet。
• 集合类型不应读取为 java.lang.String，因为那并不是一种有效的数据表示方式（例如：数组中的字符串值不会被加引号）。
• Map 映射为 JAVA_OBJECT，因为其值只能通过 getObject(columnIndex, Class<T>) 方法读取。
  • Map 不是 java.sql.Struct，因为它没有具名列。
• Tuple 映射为 Object[]，因为它可以包含不同类型的数据，使用 List 并不合适。
• Tuple 可以通过调用 getObject(columnIndex, Array.class) 方法作为 Array 读取。在这种情况下，Array#baseTypeName 将返回 Tuple 的列定义。

地理类型

ClickHouse 类型	JDBC 类型	Java 类
Point	OTHER	double[]
Ring	OTHER	double[][]
Polygon	OTHER	double[][][]
MultiPolygon	OTHER	double[][][][]

Nullable 和 LowCardinality 类型

• Nullable 和 LowCardinality 是用于包装其他类型的特殊类型。
• Nullable 会影响 ResultSetMetaData 返回类型名称的方式

特殊类型

ClickHouse 类型	JDBC 类型	Java 类
UUID	OTHER	java.util.UUID
IPv4	OTHER	java.net.Inet4Address
IPv6	OTHER	java.net.Inet6Address
JSON	OTHER	java.lang.String
AggregateFunction	OTHER	（二进制表示）
SimpleAggregateFunction	（包装类型）	（包装类）

• UUID 不是 JDBC 标准类型，但它是 JDK 的一部分。默认情况下，通过 getObject() 方法会返回 java.util.UUID 实例。
• 可以使用 getObject(columnIndex, String.class) 方法，将 UUID 以 String 的形式进行读写。
• IPv4 和 IPv6 不是 JDBC 标准类型，但它们属于 JDK 的一部分。默认情况下，通过 getObject() 方法会返回 java.net.Inet4Address 和 java.net.Inet6Address。
• IPv4 和 IPv6 可以通过 getObject(columnIndex, String.class) 方法以 String 形式进行读写。

处理日期、时间和时区

java.sql.Date、java.sql.Time 和 java.sql.Timestamp 可能会使时区计算变得复杂——尽管它们当然是受支持的, 您可以考虑使用 java.time 包。ZonedDateTime 和 OffsetDateTime 都是 java.sql.Timestamp、java.sql.Date 和 java.sql.Time 的理想替代方案。

Date 与 DateTime

Date 存储时不包含时区信息,而 DateTime 存储时包含时区信息。如果不注意这一点,可能会导致意外结果。

创建连接

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
    }
}

更多信息

如需了解更多信息,请参阅我们的 GitHub 仓库和 Java 客户端文档。

故障排除

日志

该驱动使用 slf4j 进行日志记录,并将使用 classpath 中首个可用的实现。

解决大批量插入时的 JDBC 超时问题

在 ClickHouse 中执行耗时较长的大批量插入操作时,可能会遇到如下 JDBC 超时错误:

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

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

macOS

在 macOS 上,可以调整以下设置以解决此问题:

• 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 处理套接字 keep-alive 设置的方式不同,需要执行额外的步骤。请按照以下步骤操作:

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. 修改内核参数后，运行以下命令使更改生效：

sudo sysctl -p

设置这些配置后,您需要确保客户端在套接字上启用 Keep-Alive 选项:

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

迁移指南

主要变更

功能	V1（旧版）	V2（新版）
事务支持	部分支持	不支持
响应列重命名	部分支持	不支持
多语句 SQL	不支持	不允许
命名参数	支持	不支持（JDBC 规范未定义）
使用 PreparedStatement 进行流式数据传输	支持	不支持

• JDBC V2 采用更轻量级的实现，因此移除了一些功能。
  • 在 JDBC V2 中不支持流式数据传输，因为它既不属于 JDBC 规范，也不属于 Java 标准的一部分。
• JDBC V2 需要显式配置。不提供任何故障转移相关的默认设置。
  • 协议应在 URL 中显式指定，不进行基于端口号的隐式协议检测。

配置更改

仅有两个枚举:

• com.clickhouse.jdbc.DriverProperties - 驱动程序自身的配置属性。
• com.clickhouse.client.api.ClientConfigProperties - 客户端配置相关属性。关于客户端配置变更的说明，请参见 Java Client 文档。

连接属性按以下方式解析:

• 会优先从 URL 中解析属性，这些属性将覆盖所有其他属性。
• 驱动属性不会被传递给客户端。
• 从 URL 中解析端点（主机、端口、协议）。

示例:

String url = "jdbc:ch://my-server:8443/default?" +
            "jdbc_ignore_unsupported_values=true&" +
            "socket_rcvbuf=800000";

Properties properties = new Properties();
properties.setProperty("socket_rcvbuf", "900000");
try (Connection conn = DriverManager.getConnection(url, properties)) {
    // Connection will use socket_rcvbuf=800000 and jdbc_ignore_unsupported_values=true
    // Endpoints: my-server:8443 protocol: http (not secure)
    // Database: default
}

数据类型变更

数值类型

ClickHouse 类型	是否与 V1 兼容	JDBC 类型（V2）	Java 类（V2）	JDBC 类型（V1）	Java 类（V1）
Int8	✅	TINYINT	java.lang.Byte	TINYINT	java.lang.Byte
Int16	✅	SMALLINT	java.lang.Short	SMALLINT	java.lang.Short
Int32	✅	INTEGER	java.lang.Integer	INTEGER	java.lang.Integer
Int64	✅	BIGINT	java.lang.Long	BIGINT	java.lang.Long
Int128	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
Int256	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
UInt8	❌	OTHER	java.lang.Short	OTHER	com.clickhouse.data.value.UnsignedByte
UInt16	❌	OTHER	java.lang.Integer	OTHER	com.clickhouse.data.value.UnsignedShort
UInt32	❌	OTHER	java.lang.Long	OTHER	com.clickhouse.data.value.UnsignedInteger
UInt64	❌	OTHER	java.math.BigInteger	OTHER	com.clickhouse.data.value.UnsignedLong
UInt128	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
UInt256	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
Float32	✅	REAL	java.lang.Float	REAL	java.lang.Float
Float64	✅	DOUBLE	java.lang.Double	DOUBLE	java.lang.Double
Decimal32	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal64	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal128	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal256	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Bool	✅	BOOLEAN	java.lang.Boolean	BOOLEAN	java.lang.Boolean

• 主要区别在于：为提高可移植性，无符号类型现在映射为标准 Java 类型。

字符串类型

ClickHouse 类型	是否更改	JDBC 类型（V2）	Java 类（V2）	JDBC 类型（V1）	Java 类（V1）
String	✅	VARCHAR	java.lang.String	VARCHAR	java.lang.String
FixedString	✅	VARCHAR	java.lang.String	VARCHAR	java.lang.String

• FixedString 在两个版本中都会按原样读取。例如，对于 'John'，FixedString(10) 将会被读取为 'John\0\0\0\0\0\0\0\0\0'。
• 当使用 PreparedStatement#setBytes 时，其值会先被转换为 unhex('<hex_string>')，然后按 String 类型读取。

日期/时间类型

ClickHouse 类型	与 V1 兼容	JDBC 类型（V2）	Java 类（V2）	JDBC 类型（V1）	Java 类（V1）
Date	❌	DATE	java.sql.Date	DATE	java.time.LocalDate
Date32	❌	DATE	java.sql.Date	DATE	java.time.LocalDate
DateTime	❌	TIMESTAMP	java.sql.Timestamp	TIMESTAMP	java.time.OffsetDateTime
DateTime64	❌	TIMESTAMP	java.sql.Timestamp	TIMESTAMP	java.time.OffsetDateTime
Time	✅	TIME	java.sql.Time	新类型/不支持	新类型/不支持
Time64	✅	TIME	java.sql.Time	新类型 / 不受支持	新类型 / 不受支持

• Time 和 Time64 仅在 V2 中作为新增类型得到支持。
• DateTime 和 DateTime64 映射到 java.sql.Timestamp，以实现更好的 JDBC 兼容性。

枚举类型

ClickHouse 类型	是否已更改	JDBC 类型（V2）	Java 类（V2）	JDBC 类型（V1）	Java 类（V1）
Enum	✅	VARCHAR	java.lang.String	OTHER	java.lang.String
Enum8	✅	VARCHAR	java.lang.String	OTHER	java.lang.String
Enum16	✅	VARCHAR	java.lang.String	OTHER	java.lang.String

采集类型

ClickHouse 类型	是否变更	JDBC 类型（V2）	Java 类（V2）	JDBC 类型（V1）	Java 类（V1）
Array	❌	ARRAY	java.sql.Array	ARRAY	Object[] 或原始类型的数组
Tuple	❌	OTHER	Object[]	STRUCT	java.sql.Struct
Map	❌	JAVA_OBJECT	java.util.Map	STRUCT	java.util.Map

• 在 V2 中，Array 默认映射为 java.sql.Array，以保证与 JDBC 的兼容性。这也能提供更多关于返回数组值的信息，便于类型推断。
• 在 V2 中，Array 实现了 getResultSet() 方法，以返回一个内容与原始数组相同的 java.sql.ResultSet 对象。
• V1 对 Map 使用 STRUCT，但始终返回 java.util.Map 对象。V2 通过将 Map 映射为 JAVA_OBJECT 修复了这一点。此外，将 Map 映射为 STRUCT 也是不正确的，因为 Map 本身并不包含具名列。
• V1 对 Tuple 使用 STRUCT，但始终返回 List<Object> 对象。V2 通过将 Tuple 映射为 OTHER 并返回 Object[] 来修复此问题，因为 Tuple 中可以包含不同类型元素，使用 List 作为返回类型并不合适。
• PreparedStatement#setBytes 和 ResultSet#getBytes 不能与集合类型一起使用。这些方法是为处理二进制字符串而设计的。
• 通常会使用 java.sql.Array 来读写 Array 类型。JDBC 驱动对此提供了完备支持。

地理类型

ClickHouse 类型	是否与 V1 兼容	JDBC 类型（V2）	Java 类（V2）	JDBC 类型（V1）	Java 类（V1）
Point	✅	OTHER	double[]	OTHER	double[]
Ring	✅	OTHER	double[][]	OTHER	double[][]
Polygon	✅	OTHER	double[][][]	OTHER	double[][][]
MultiPolygon	✅	OTHER	double[][][][]	OTHER	double[][][][]

Nullable 和 LowCardinality 类型

• Nullable 和 LowCardinality 是用于封装其他类型的特殊类型。
• 在 V2 中，这些类型没有更改。

特殊类型

ClickHouse 类型	与 V1 兼容	JDBC 类型（V2）	Java 类（V2）	JDBC 类型（V1）	Java 类（V1）
JSON	❌	OTHER	java.lang.String	不支持	不支持
AggregateFunction	✅	OTHER	（二进制表示）	OTHER	（二进制表示）
SimpleAggregateFunction	✅	（封装类型）	（封装类）	（封装类型）	（封装类）
UUID	✅	OTHER	java.util.UUID	VARCHAR	java.util.UUID
IPv4	✅	OTHER	java.net.Inet4Address	VARCHAR	java.net.Inet4Address
IPv6	✅	OTHER	java.net.Inet6Address	VARCHAR	java.net.Inet6Address
Dynamic	❌	OTHER	java.lang.Object	不支持	不支持
Variant	❌	OTHER	java.lang.Object	不支持	不支持

• V1 将 UUID 映射为 VARCHAR 类型，但始终返回 java.util.UUID 对象。V2 通过将 UUID 映射到 OTHER 并同样返回 java.util.UUID 对象来修复了这一问题。
• V1 对 IPv4 和 IPv6 使用 VARCHAR 类型，但始终返回 java.net.Inet4Address 和 java.net.Inet6Address 对象。V2 通过将 IPv4 和 IPv6 映射为 JDBC 类型 OTHER，并返回 java.net.Inet4Address 和 java.net.Inet6Address 对象来修复此问题。
• Dynamic 和 Variant 是在 V2 中引入的新类型。在 V1 中不支持。
• JSON 基于 Dynamic 类型，因此仅在 V2 中受支持。
• 可以通过 getBytes(columnIndex) 方法将 IPv4 和 IPv6 的值读取为 byte[]。不过，建议为这些类型使用专用的类。
• V2 不支持将 IP 地址读取为数值形式，因为在 InetAddress 类中进行转换的实现更为合适。

数据库元数据变更

• V2 仅使用 Schema 一词来表示数据库。Catalog 一词保留供将来使用。
• V2 会在 DatabaseMetaData.supportsTransactions() 和 DatabaseMetaData.supportsSavepoints() 中返回 false。这一点将在后续开发中进行修改。

clickhouse-jdbc 实现了标准的 JDBC 接口。它基于 clickhouse-client 构建,提供了自定义类型映射、事务支持以及标准同步 UPDATE 和 DELETE 语句等附加功能,因此可以轻松地与传统应用程序和工具集成使用。

注意

最新的 JDBC（0.7.2）版本使用 Client-V1

clickhouse-jdbc API 是同步的,通常会产生更多开销(例如 SQL 解析和类型映射/转换等)。当性能至关重要或您希望以更直接的方式访问 ClickHouse 时,请考虑使用 clickhouse-client。

环境要求

• OpenJDK 8 或更高版本

设置

Maven

<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.7.2</version>
    <!-- 使用包含所有依赖的 uber JAR，将 classifier 修改为 http 以减小 JAR 体积 -->
    <classifier>shaded-all</classifier>
</dependency>

Gradle (Kotlin)

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
// 使用包含所有依赖的 uber JAR，将 classifier 修改为 http 以减小 JAR 体积
implementation("com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all")

Gradle

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
// 使用包含所有依赖的 uber JAR，将 classifier 修改为 http 以减小 JAR 体积
implementation 'com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all'

从版本 0.5.0 开始,我们使用了打包在客户端中的 Apache HTTP Client。由于该包不存在共享版本,您需要将日志记录器作为依赖项添加。

Maven

<!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-api -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.16</version>
</dependency>

Gradle（Kotlin）

// https://mvnrepository.com/artifact/org.slf4j/slf4j-api
implementation("org.slf4j:slf4j-api:2.0.16")

Gradle

// https://mvnrepository.com/artifact/org.slf4j/slf4j-api
implementation 'org.slf4j:slf4j-api:2.0.16'

配置

驱动程序类: com.clickhouse.jdbc.ClickHouseDriver

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

• jdbc:ch://localhost 等同于 jdbc:clickhouse:http://localhost:8123
• jdbc:ch:https://localhost 等价于 jdbc:clickhouse:http://localhost:8443?ssl=true&sslmode=STRICT
• jdbc:ch:grpc://localhost 与 jdbc:clickhouse:grpc://localhost:9100 是等价的

连接属性:

属性	默认值	说明
continueBatchOnError	false	是否在发生错误时继续执行批处理操作
createDatabaseIfNotExist	false	是否在数据库不存在时自动创建数据库
custom_http_headers		以逗号分隔的自定义 HTTP 请求头，例如：User-Agent=client1,X-Gateway-Id=123
custom_http_params		用逗号分隔的自定义 HTTP 查询参数，例如：extremes=0,max_result_rows=100
nullAsDefault	0	0 - 按原样处理 null 值，在向非 Nullable 列插入 null 时抛出异常；1 - 按原样处理 null 值，并在插入时禁用对 null 的检查；2 - 将 null 替换为相应数据类型的默认值（对查询和插入均生效）
jdbcCompliance	true	是否支持标准的同步 UPDATE/DELETE 操作以及伪事务机制
typeMappings		自定义 ClickHouse 数据类型与 Java 类之间的映射，该配置会同时影响 getColumnType() 和 getObject(Class<>?>) 的返回结果。例如：UInt128=java.lang.String,UInt256=java.lang.String
wrapperObject	false	getObject() 是否应针对 Array / Tuple 返回 java.sql.Array / java.sql.Struct。

注意:更多信息请参考 JDBC 特定配置。

支持的数据类型

JDBC 驱动支持与客户端库相同的数据格式。

注意

• AggregatedFunction - ⚠️ 不支持通过 SELECT * FROM table ... 查询
• Decimal - 在 21.9+ 中使用 SET output_format_decimal_trailing_zeros=1 以保持结果一致性
• Enum - 既可以作为字符串，也可以作为整数处理
• UInt64 - 在 client-v1 中映射为 long

创建连接

String url = "jdbc:ch://my-server/system"; // use http protocol and port 8123 by default

Properties properties = new Properties();

ClickHouseDataSource dataSource = new ClickHouseDataSource(url, properties);
try (Connection conn = dataSource.getConnection("default", "password");
    Statement stmt = conn.createStatement()) {
}

简单语句

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

插入

注意

• 使用 PreparedStatement 而不是 Statement

它更易于使用,但性能比 input 函数慢(见下文):

try (PreparedStatement ps = conn.prepareStatement("insert into mytable(* except (description))")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.addBatch(); // parameters will be write into buffered stream immediately in binary format
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

使用 input 表函数

一个性能表现优异的选项:

try (PreparedStatement ps = conn.prepareStatement(
    "insert into mytable select col1, col2 from input('col1 String, col2 DateTime64(3), col3 Int32')")) {
    // The column definition will be parsed so the driver knows there are 3 parameters: col1, col2 and col3
    ps.setString(1, "test"); // col1
    ps.setObject(2, LocalDateTime.now()); // col2, setTimestamp is slow and not recommended
    ps.setInt(3, 123); // col3
    ps.addBatch(); // parameters will be write into buffered stream immediately in binary format
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

• input 表函数文档，并在可能的情况下优先使用该函数

使用占位符插入数据

此选项仅建议用于小批量插入,因为它需要较长的 SQL 表达式(该表达式将在客户端解析并消耗 CPU & 内存):

try (PreparedStatement ps = conn.prepareStatement("insert into mytable values(trim(?),?,?)")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.setString(3, null); // description
    ps.addBatch(); // append parameters to the query
    ...
    ps.executeBatch(); // issue the composed query: insert into mytable values(...)(...)...(...)
}

处理 DateTime 和时区

请使用 java.time.LocalDateTime 或 java.time.OffsetDateTime 代替 java.sql.Timestamp,并使用 java.time.LocalDate 代替 java.sql.Date。

try (PreparedStatement ps = conn.prepareStatement("select date_time from mytable where date_time > ?")) {
    ps.setObject(2, LocalDateTime.now());
    ResultSet rs = ps.executeQuery();
    while(rs.next()) {
        LocalDateTime dateTime = (LocalDateTime) rs.getObject(1);
    }
    ...
}

处理 AggregateFunction

注意

目前仅支持 groupBitmap。

// batch insert using input function
try (ClickHouseConnection conn = newConnection(props);
        Statement s = conn.createStatement();
        PreparedStatement stmt = conn.prepareStatement(
                "insert into test_batch_input select id, name, value from input('id Int32, name Nullable(String), desc Nullable(String), value AggregateFunction(groupBitmap, UInt32)')")) {
    s.execute("drop table if exists test_batch_input;"
            + "create table test_batch_input(id Int32, name Nullable(String), value AggregateFunction(groupBitmap, UInt32))engine=Memory");
    Object[][] objs = new Object[][] {
            new Object[] { 1, "a", "aaaaa", ClickHouseBitmap.wrap(1, 2, 3, 4, 5) },
            new Object[] { 2, "b", null, ClickHouseBitmap.wrap(6, 7, 8, 9, 10) },
            new Object[] { 3, null, "33333", ClickHouseBitmap.wrap(11, 12, 13) }
    };
    for (Object[] v : objs) {
        stmt.setInt(1, (int) v[0]);
        stmt.setString(2, (String) v[1]);
        stmt.setString(3, (String) v[2]);
        stmt.setObject(4, v[3]);
        stmt.addBatch();
    }
    int[] results = stmt.executeBatch();
    ...
}

// use bitmap as query parameter
try (PreparedStatement stmt = conn.prepareStatement(
    "SELECT bitmapContains(my_bitmap, toUInt32(1)) as v1, bitmapContains(my_bitmap, toUInt32(2)) as v2 from {tt 'ext_table'}")) {
    stmt.setObject(1, ClickHouseExternalTable.builder().name("ext_table")
            .columns("my_bitmap AggregateFunction(groupBitmap,UInt32)").format(ClickHouseFormat.RowBinary)
            .content(new ByteArrayInputStream(ClickHouseBitmap.wrap(1, 3, 5).toBytes()))
            .asTempTable()
            .build());
    ResultSet rs = stmt.executeQuery();
    Assert.assertTrue(rs.next());
    Assert.assertEquals(rs.getInt(1), 1);
    Assert.assertEquals(rs.getInt(2), 0);
    Assert.assertFalse(rs.next());
}

配置 HTTP 库

ClickHouse JDBC 连接器支持三个 HTTP 库:HttpClient、HttpURLConnection 和 Apache HttpClient。

注意

HttpClient 仅支持 JDK 11 及以上版本。

JDBC 驱动程序默认使用 HttpClient。您可以通过设置以下属性来更改 ClickHouse JDBC 连接器所使用的 HTTP 库:

properties.setProperty("http_connection_provider", "APACHE_HTTP_CLIENT");

以下是对应值的完整列表:

属性值	HTTP 客户端库
HTTP_CLIENT	HttpClient
HTTP_URL_CONNECTION	HttpURLConnection
APACHE_HTTP_CLIENT	Apache HttpClient

通过 SSL 连接到 ClickHouse

要使用 SSL 建立到 ClickHouse 的安全 JDBC 连接,需要配置 JDBC 属性以包含 SSL 参数。这通常需要在 JDBC URL 或 Properties 对象中指定 SSL 属性,如 sslmode 和 sslrootcert。

SSL 属性

名称	默认值	可选值	说明
ssl	false	true, false	是否为该连接启用 SSL/TLS
sslmode	strict	strict, none	是否校验 SSL/TLS 证书
sslrootcert			SSL/TLS 根证书文件路径
sslcert			SSL/TLS 证书文件路径
sslkey			PKCS#8 格式的 RSA 私钥
key_store_type		JKS, PKCS12	指定 KeyStore/TrustStore 文件的类型或格式
trust_store			TrustStore 文件路径
key_store_password			用于访问 KeyStore 配置中所指定 KeyStore 文件的密码

这些属性可确保您的 Java 应用程序通过加密连接与 ClickHouse 服务器进行通信,从而提高数据传输过程中的安全性。

  String url = "jdbc:ch://your-server:8443/system";

  Properties properties = new Properties();
  properties.setProperty("ssl", "true");
  properties.setProperty("sslmode", "strict"); // NONE to trust all servers; STRICT for trusted only
  properties.setProperty("sslrootcert", "/mine.crt");
  try (Connection con = DriverManager
          .getConnection(url, properties)) {

      try (PreparedStatement stmt = con.prepareStatement(

          // place your code here

      }
  }

解决大批量插入时的 JDBC 超时问题

在 ClickHouse 中执行耗时较长的大批量插入操作时,可能会遇到如下 JDBC 超时错误:

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

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

macOS

在 macOS 上,可以调整以下设置以解决此问题:

• 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 处理套接字 keep-alive 设置的方式不同,需要执行额外的步骤。请按照以下步骤操作:

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. 修改内核参数后，运行以下命令使更改生效：

sudo sysctl -p

设置这些配置后,您需要确保客户端在套接字上启用 Keep-Alive 选项:

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

注意

目前,在设置套接字保活功能时,必须使用 Apache HTTP Client 库,因为 clickhouse-java 支持的其他两个 HTTP 客户端库不允许设置套接字选项。详细指南请参阅配置 HTTP 库。

或者,您可以在 JDBC URL 中添加等效参数。

JDBC 驱动程序的默认套接字和连接超时时间为 30 秒。可以增加超时时间以支持大规模数据插入操作。使用 ClickHouseClient 的 options 方法,结合 ClickHouseClientOption 中定义的 SOCKET_TIMEOUT 和 CONNECTION_TIMEOUT 选项:

final int MS_12H = 12 * 60 * 60 * 1000; // 12 h in ms
final String sql = "insert into table_a (c1, c2, c3) select c1, c2, c3 from table_b;";

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP)) {
    client.read(servers).write()
        .option(ClickHouseClientOption.SOCKET_TIMEOUT, MS_12H)
        .option(ClickHouseClientOption.CONNECTION_TIMEOUT, MS_12H)
        .query(sql)
        .executeAndWait();
}