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.7</version>
    <classifier>all</classifier>
</dependency>

Gradle（Kotlin）

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

Gradle

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

如果您在需要显式将 JAR 添加到 classpath 的应用程序中使用 JDBC 驱动程序，则需要从以下地址下载该 JAR 文件：

• Maven Central，然后将其添加到 classpath 中
  • 从版本 0.9.4 开始，提供了一个构件：https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all
  • 使用限定符 all 即可获取包含所有打包 (shaded) 依赖的 jar 包。
• 或者从官方仓库

配置

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

注意

com.clickhouse.jdbc.ClickHouseDriver 是新旧 JDBC 实现的外观类，默认使用新的 JDBC 实现。 如需使用旧版 JDBC 实现，可将 clickhouse.jdbc.v1 系统属性设置为 true。该属性应在调用 Driver 类之前设置。

切换不同版本的另一种方式是直接使用各版本对应的 Driver 类：

• com.clickhouse.jdbc.Driver 是新的 JDBC 实现 (V2) 。
• com.clickhouse.jdbc.DriverV1 是旧版的 JDBC 实现 (V1) 。

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。
remember_last_set_roles	true	记住此连接上最近设置的角色。

服务器设置

所有服务器设置都应以 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 编码，驱动程序会自动完成编码。

客户端标识

有两种方式可以标识发起请求的应用程序：通过连接属性设置 com.clickhouse.client.api.ClientConfigProperties#CLIENT_NAME，或使用 java.sql.Connection#setClientInfo(String name, String value) 方法。

Properties properties = new Properties();
properties.setProperty(ClientConfigProperties.CLIENT_NAME.getKey(), "my-app-01");
Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);

conn.setClientInfo(com.clickhouse.jdbc.ClientInfoProperties.APPLICATION_NAME.getKey(), "my-app-01");

两种方式都会在查询日志中生成以下 http_user_agent 值：

my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4

操作标识

JDBC 驱动程序会为每个操作生成一个 query_id (目前该 ID 会出现在服务器异常信息中) 。

要为某个操作设置 log_comment，请使用 com.clickhouse.jdbc.StatementImpl#getLocalSettings 方法。这需要先将 Statement 或 PreparedStatement 强制转换为 com.clickhouse.jdbc.StatementImpl。

StatementImpl stmt = (StatementImpl) conn.createStatement();
stmt.getLocalSettings().logComment("some-comment");

注意： 该方法仅适用于在单线程中使用 Statement 的场景，因为 localSettings 会在各线程间共享。

支持的数据类型

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) 如果值落在 Byte 可表示的范围内，可以返回 Int16 列的 Byte 值。
• 由于存在数据损坏风险，不建议将较宽范围的类型转换为较窄范围的类型。
• Bool 类型也可以视为数值类型使用。
• 所有数值类型都可以读取为 java.lang.String 类型。
• 将 Java Float.MAX_VALUE 作为 Float 存储时会出现问题 (https://github.com/ClickHouse/clickhouse-java/issues/809) 。将相同的值以 Double 类型存储可以解决该问题。

字符串类型

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 中以字符串或数值形式进行设置。

日期/时间类型

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 会受到服务器或会话时区的影响。
• DateTime 和 DateTime64 可以通过 getObject(colIndex, ZonedDateTime.class) 将其读取为 ZonedDateTime 对象。

嵌套类型

ClickHouse 类型	JDBC 类型	Java 类
Array	ARRAY	java.sql.Array
Tuple	OTHER	com.clickhouse.data.Tuple
Map	JAVA_OBJECT	java.util.Map
Nested	ARRAY	java.sql.Array

• 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 列的定义。

写入数组

使用 java.sql.Connection#createArrayOf 来实例化 java.sql.Array 对象。该对象旨在统一不同数据库中的数组处理方式。 需要通过 Connection 将配置传递给 Array 的工厂方法。

该方法接受两个参数：

• typeName - 数组元素类型的名称。例如 Array(Int32) -> "Int32"。
• elements - 实际的数组元素。例如 [[1, 2, 3], [4, 5, 6]] -> new Integer[][] {{1, 2, 3}, {4, 5, 6}}。

Tuple 可以表示为 Object[] 或 java.sql.Struct (请参阅下文中关于如何写入 Tuple 的说明) 。

示例

try (Connection conn = ...) {
    Array array = conn.createArrayOf("Int32", new Integer[][] {{1, 2, 3}, {4, 5, 6}});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (arr) VALUES (?)")) {
        ps.setArray(1, array);
        ps.executeUpdate();
    }
}

读取数组

使用 ResultSet#getArray(columnIndex) 读取 Array 对象。该对象可用于访问任意嵌套深度的数组。 Array#getResultSet() 方法可以以类似 java.sql.ResultSet 的、更统一的方式读取数组元素，在数组元素的确切类型未知时尤为有用。

示例

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Array(Int32)")) {
        ps.setArray(1, array);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Array array = rs.getArray(1);

                Object[] arr = (Object[]) array;
                Arrays.stream(arr).forEach(this::handleArrayElement);

                // or by using `ResultSet`
                ResultSet resultSet = array.getResultSet();
                while (resultSet.next()) {
                    // ...
                }
            }
        }
    } 
}

写入元组

Tuple 会映射为 com.clickhouse.data.Tuple 对象，应通过调用 setObject(columnIndex, tuple) 方法，以该对象形式写入。 也可以使用 java.sql.Struct 对象来写入 Tuple，以提高可移植性。

示例

try (Connection conn = ...) {
    Tuple tuple = new Tuple(1, "test", LocalDate.parse("2026-03-02"));
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (tuple) VALUES (?)")) {
        ps.setObject(1, tuple);
        ps.executeUpdate();
    }
}

try (Connection conn = ...) {
    Struct struct = conn.createStruct("Tuple(Int32, String, Date)", new Object[] {1, "test", LocalDate.parse("2026-03-02")});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (tuple) VALUES (?)")) {
        ps.setStruct(1, struct);
        ps.executeUpdate();
    }
}

读取 Tuple 类型

方法 getObject(columnIndex) 会返回 Object[]。通过调用 getObject(columnIndex, Array.class) 方法，可以将 Tuple 读取为 java.sql.Array。

示例

try (Connection conn = ...) {
    try (PreparedStatement stmt = conn.prepareStatement("SELECT ?::Tuple(String, Int32, Date)")) {
        Array tuple = conn.createArrayOf("Tuple(String, Int32, Date)",  new Object[]{"test", 123, LocalDate.parse("2026-03-02")});
        stmt.setObject(1, tuple);
        try (ResultSet rs = stmt.executeQuery()) {
            rs.next();
            Array dbTuple = rs.getArray(1);
            Assert.assertEquals(dbTuple, tuple);
            Object arr = rs.getObject(1);
            Assert.assertEquals(arr, tuple.getArray());
        }
    }
}

写入 Map 类型

只能将 Map 作为 java.collections.Map 对象写入，因为该类型需要键值对 (java.sql.Struct 不支持键值对) 。

示例

try (Connection conn = ...) {
    Map<String, Integer> map = new HashMap<>();
    map.put("key1", 1);
    map.put("key2", 2);
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (map) VALUES (?)")) {
        ps.setObject(1, map);
        ps.executeUpdate();
    }
}

读取 Map 类型

可以通过 getObject(columnIndex, Map.class) 方法将 Map 读取为 java.util.Map 对象。

示例

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Map(String, Int32)")) {
        ps.setStruct(1, struct);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Map<String, Integer> map = rs.getObject(1, Map.class);
                // ...
            }
        }
    }
}

写入嵌套

使用 java.sql.Connection#createStruct 来实例化 java.sql.Struct 对象。此对象旨在在不同数据库之间统一嵌套处理的方式。 需要通过 Connection 将配置信息传递给 Struct 的工厂方法。

该方法接收两个参数：

• typeName - 嵌套元素的类型名称。例如 Nested(Tuple(Int32, String)) -> "Nested(Tuple(Int32, String))"。
• elements - 实际的嵌套元素。例如 [1, 'test'] -> new Object[] {1, 'test'}.

示例

try (Connection conn = ...) {
    Struct struct = conn.createStruct("Nested(Tuple(Int32, String))", new Object[] {1, 'test'});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (nested) VALUES (?)")) {
        ps.setStruct(1, struct);
        ps.executeUpdate();
    }
}

读取嵌套类型

使用 ResultSet#getStruct(columnIndex, StructDescriptor) 读取 Nested 对象。该对象可用于访问任意嵌套深度的嵌套结构。 可以使用 Struct#getResultSet() 方法，以类似于 java.sql.ResultSet 的更统一方式读取嵌套元素。当嵌套元素的确切类型未知时，这非常有用。

示例

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Nested(Tuple(Int32, String))")) {
        ps.setStruct(1, struct);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Struct struct = rs.getStruct(1);
                Object[] tuple = (Object[]) struct;
                Arrays.stream(tuple).forEach(this::handleTupleElement);

                // or by using `ResultSet`
                ResultSet resultSet = struct.getResultSet();
                while (resultSet.next()) {
                    // ...
                }
            }
        }
    }
}

地理类型

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 形式读取/写入。

处理日期、时间和时区

请阅读 日期/时间指南，该指南解释了驱动程序在处理日期/时间和时间戳时的常见陷阱与逻辑。

创建连接

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]

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

Mac OS

在 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 中解析得到。

Example:

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 类型	与 V1 兼容	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 读取。
• 字符串以 UTF-8 编码存储。

日期和时间类型

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 类型	与 V1 兼容	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 类型	与 V1 兼容	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
Nested	❌	ARRAY	java.sql.Array	STRUCT	java.sql.Struct

• 在 V2 中，Array 默认会映射为 java.sql.Array，以确保与 JDBC 的兼容性。这也能够提供关于返回数组值的更多信息，有助于进行类型推断。
• 在 V2 中，Array 实现了 getResultSet() 方法，用于返回一个与原始数组内容相同的 java.sql.ResultSet 对象。
• V1 对 Map 使用 STRUCT，但始终返回 java.util.Map 对象。V2 通过将 Map 映射为 JAVA_OBJECT 解决了这一问题。
• V1 使用 STRUCT 作为 Tuple 的 JDBC 类型，但始终返回 List<Object> 对象。V2 将 Tuple 映射为 OTHER，默认返回 Object[]。
• V2 引入了 com.clickhouse.data.Tuple#Tuple，用于写入 Tuple，从而简化判断某个值是 Tuple 还是数组。
• PreparedStatement#setBytes 和 ResultSet#getBytes 不能与集合类型一起使用。这些方法是为处理二进制字符串而设计的。
• 通常使用 java.sql.Array 来写入和读取 Array 类型。JDBC 驱动对此提供了完整支持。
• 在 V2 中，Nested 被映射为 Array，并将其表示为元组数组。
• V2 对 java.sql.Struct 提供了部分支持，因为它与 Array 类型非常相似，而且不支持键值对。Struct 可用于写入 Tuple 类型的值。

地理空间类型

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 使用 VARCHAR 作为 UUID 的 JDBC 类型，但始终返回 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 中可用。
• IPv4 和 IPv6 值可以通过 getBytes(columnIndex) 方法读取为 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 对象中指定 sslmode、sslrootcert 等 SSL 属性。

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]

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

Mac OS

在 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");

注意

目前，在为套接字设置 keep-alive 时，必须使用 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();
}