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'

如果您在应用程序中使用 JDBC 驱动程序，且该应用程序需要将 jar 添加到 classpath，则需要从以下地址下载 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。

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 实现，而不是新版实现
default_query_settings	null	允许在执行查询时传递默认查询设置
jdbc_resultset_auto_close	true	在关闭 Statement 时自动关闭 ResultSet
beta.row_binary_for_simple_insert	false	使用基于 RowBinary writer 的 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 值。
  • 如果值在 Byte 的取值范围内，rs.getByte(1) 可以返回 Int16 列的 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 中将枚举值设置为字符串值或数值。

日期/时间类型

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 类型

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.collections.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) 方法以 String 形式对 UUID 进行读写。
• IPv4 和 IPv6 不是 JDBC 标准类型，但它们是 JDK 的一部分。默认情况下，调用 getObject() 方法时会返回 java.net.Inet4Address 和 java.net.Inet6Address 实例。
• 通过 getObject(columnIndex, String.class) 方法，IPv4 和 IPv6 可以以 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]

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

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 中解析而来。

示例：

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 将 Tuple 映射为 STRUCT，但始终返回 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 中受支持。
• 可以通过 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]

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

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

注意

目前,在设置套接字保活功能时,必须使用 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();
}