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

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

примечание

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

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

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

Старая функция	Примечания
Поддержка транзакций	Ранние версии драйвера имитировали поддержку транзакций, что могло привести к неожиданным результатам.
Переименование столбцов ответа	ResultSet стал неизменяемым - для повышения эффективности они теперь только для чтения
Поддержка многоинструкционного SQL	Поддержка многоинструкционного SQL была только симулирована, теперь она строго соответствует 1:1
Именованные параметры	Не входят в спецификацию JDBC
Потоковая PreparedStatement	Ранние версии драйвера позволяли использование PreparedStatement вне JDBC - если вам нужны такие опции, мы рекомендуем посмотреть на 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 в сокете: