跳到主要内容
跳到主要内容

JDBC 驱动程序 (0.8+)

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

备注

如果您正在寻找 JDBC 驱动程序文档的先前版本，请参见 这里。

从 0.7.x 的变更​

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

旧功能说明
事务支持驱动程序的早期版本仅 模拟 了事务支持，这可能会导致意外结果。
响应列重命名ResultSet 是可变的 - 出于效率考虑，它们现在是只读的
多语句 SQL多语句支持仅是 模拟 的，现在严格遵循 1:1
命名参数不是 JDBC 规范的一部分
基于流的 PreparedStatement驱动程序的早期版本允许非 JDBC 使用 PreparedStatement - 如果您需要此类选项，我们建议查看 Java Client 及其 示例。
备注

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

环境要求​

设置​

配置​

驱动类: com.clickhouse.jdbc.ClickHouseDriver

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

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

连接属性:

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

属性默认描述
disable_frameworks_detectiontrue禁用用户代理的框架检测
jdbc_ignore_unsupported_valuesfalse抑制 SQLFeatureNotSupportedException
clickhouse.jdbc.v1false使用旧的 JDBC 实现，而不是新的 JDBC
default_query_settingsnull允许在查询操作中传递默认的查询设置

支持的数据类型​

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

处理日期、时间和时区​

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

创建连接​

提供凭证和设置​

简单语句​

插入​

HikariCP​

更多信息​

有关更多信息，请查看我们的 GitHub 代码库 和 Java Client 文档。

故障排除​

日志记录​

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

解决大型插入的 JDBC 超时​

在 ClickHouse 中执行长时间的巨大插入时，您可能会遇到类似于以下的 JDBC 超时错误：

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

Mac OS​

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

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

Linux​

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

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

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

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

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