JDBC Driver (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 Driver поддерживает те же форматы данных, что и подлежащий 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 на сокете: