Драйвер JDBC (0.8+)

clickhouse-jdbc реализует стандартный интерфейс JDBC, используя последний java client. Мы рекомендуем использовать последний java client напрямую, если производительность/прямой доступ критичны.

примечание

Если вы ищете предыдущую версию документации по драйверу JDBC, пожалуйста, смотрите здесь.

Изменения с 0.7.x

В версии 0.8 мы попытались сделать драйвер более строго соответствующим спецификации JDBC, поэтому некоторые функции были удалены, что может повлиять на вас:

Старая функция	Примечания
Поддержка транзакций	Ранние версии драйвера только симулировали поддержку транзакций, что могло привести к неожиданным результатам.
Переименование столбцов ответа	ResultSet был изменяемым - ради эффективности теперь они только для чтения.
Многозначные SQL	Поддержка многозначных выражений была только симулирована, теперь она строго следует 1:1.
Именованные параметры	Не входят в спецификацию JDBC
Подготовленные выражения на основе потока	Ранняя версия драйвера позволяла не-JDBC использование PreparedStatement - если вам нужны такие опции, мы рекомендуем обратить внимание на Java Client и его примеры.

примечание

Date хранится без часового пояса, в то время как DateTime хранится с часовым поясом. Это может привести к неожиданным результатам, если вы не будете осторожны.

Требования к среде

• версия OpenJDK >= 8

Настройка

Maven

Gradle (Kotlin)

Gradle

Конфигурация

Класс драйвера: com.clickhouse.jdbc.ClickHouseDriver

Синтаксис URL: jdbc:(ch|clickhouse)[:<protocol>]://endpoint1[,endpoint2,...][/<database>][?param1=value1&param2=value2][#tag1,tag2,...], например:

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

Свойства подключения:

Помимо стандартных свойств JDBC, драйвер поддерживает специфические для ClickHouse свойства, предоставляемые подлежащим java client. Где это возможно, методы будут возвращать SQLFeatureNotSupportedException, если функция не поддерживается. Другие пользовательские свойства включают:

Свойство	Значение по умолчанию	Описание
disable_frameworks_detection	true	Отключить определение фреймворков для User-Agent
jdbc_ignore_unsupported_values	false	Подавляет SQLFeatureNotSupportedException
clickhouse.jdbc.v1	false	Использовать старую реализацию JDBC вместо новой JDBC
default_query_settings	null	Позволяет передавать настройки запросов по умолчанию с запросами

Поддерживаемые типы данных

Драйвер JDBC поддерживает те же форматы данных, что и подлежащий java client.

Обработка дат, времени и часовых поясов

java.sql.Date, java.sql.Time и java.sql.Timestamp могут усложнить вычисление часовых поясов - хотя они, конечно, поддерживаются, вы можете рассмотреть возможность использования пакета java.time. ZonedDateTime и OffsetDateTime являются отличными заменами для java.sql.Timestamp, java.sql.Date и java.sql.Time.

Создание соединения

Подача учетных данных и настроек

Простой оператор

Вставка

HikariCP

Дополнительная информация

Для получения дополнительной информации смотрите наш GitHub репозиторий и документацию по Java Client.

Устранение неполадок

Логирование

Драйвер использует slf4j для логирования и будет использовать первую доступную реализацию на classpath.

Решение проблем с тайм-аутами JDBC при больших вставках

При выполнении больших вставок в ClickHouse с длительным временем выполнения вы можете столкнуться с ошибками тайм-аута JDBC, такими как:

Эти ошибки могут нарушить процесс вставки данных и повлиять на стабильность системы. Для решения этой проблемы вам может потребоваться настроить несколько тайм-аутов в ОС клиента.

Mac OS

На Mac OS следующие настройки могут быть отрегулированы для решения проблемы:

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

Linux

На Linux эквивалентные настройки могут не решить проблему. Потребуются дополнительные шаги из-за различий в том, как Linux обрабатывает настройки keep-alive для сокетов. Следуйте следующим шагам:

1. Отрегулируйте следующие параметры ядра Linux в файле /etc/sysctl.conf или в связанном файле конфигурации:

   • net.inet.tcp.keepidle: 60000
   • net.inet.tcp.keepintvl: 45000
   • net.inet.tcp.keepinit: 45000
   • net.inet.tcp.keepcnt: 8
   • net.inet.tcp.always_keepalive: 1
   • net.ipv4.tcp_keepalive_intvl: 75
   • net.ipv4.tcp_keepalive_probes: 9
   • net.ipv4.tcp_keepalive_time: 60 (Вы можете рассмотреть возможность уменьшения этого значения с 300 секунд по умолчанию)

2. После изменения параметров ядра примените изменения, выполнив следующую команду:

После настройки этих параметров необходимо убедиться, что ваш клиент включает опцию Keep Alive для сокета: