Перейти к основному содержимому
Перейти к основному содержимому

JDBC-драйвер

v0.8+
Примечание

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

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

Настройка​

<!-- 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>

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

Класс драйвера: 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 допускается только одна конечная точка
  • протокол следует указывать, если используется не протокол по умолчанию — 'HTTP'
  • порт необходимо указывать, если используется не порт по умолчанию '8123'
  • драйвер не определяет протокол на основе порта, его нужно указывать явно
  • Параметр ssl не требуется, если указан протокол.

Свойства соединения​

Основные параметры конфигурации определены в java-клиенте. Их следует передавать драйверу без изменений. Драйвер имеет собственные свойства, которые не входят в конфигурацию клиента; они перечислены ниже.

Свойства драйвера:

СвойствоЗначение по умолчаниюОписание
disable_frameworks_detectiontrueОтключить определение фреймворков по заголовку User-Agent
jdbc_ignore_unsupported_valuesfalseПодавляет SQLFeatureNotSupportedException, если это не влияет на работу драйвера
clickhouse.jdbc.v1falseИспользовать старую реализацию JDBC вместо новой
default_query_settingsnullРазрешает передавать настройки запроса по умолчанию при выполнении запросов
jdbc_resultset_auto_closetrueАвтоматически закрывает ResultSet при закрытии объекта Statement
beta.row_binary_for_simple_insertfalseИспользовать реализацию PreparedStatement, основанную на механизме записи RowBinary. Работает только для запросов INSERT INTO ... VALUES.
jdbc_resultset_auto_closetrueАвтоматически закрывает ResultSet при закрытии Statement
jdbc_use_max_result_rowsfalseВключает использование серверного свойства max_result_rows для ограничения количества строк, возвращаемых запросом. При включении переопределяет режим переполнения, установленный пользователем. Подробности см. в JavaDoc.
jdbc_sql_parserJAVACCОпределяет, какой 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);

что будет эквивалентно следующему URL JDBC:

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.

Примечание: URL-кодирование JDBC URL или свойств не требуется — они будут закодированы автоматически.

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

Драйвер JDBC поддерживает те же форматы данных, что и базовый Java-клиент.

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

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

Date vs 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()) {
        // ...
    }
}

Insert​

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]

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

macOS​

В 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 одних только эквивалентных настроек может быть недостаточно для решения проблемы. Необходимы дополнительные действия из-за особенностей обработки параметров keep-alive для сокетов в Linux. Выполните следующие действия:

  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 секунд)`
  1. После изменения параметров ядра примените их, выполнив следующую команду:
sudo sysctl -p

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

properties.setProperty("socket_keepalive", "true");

Руководство по миграции​

Основные изменения​

ВозможностьV1 (устаревшая)V2 (новая)
Поддержка транзакцийЧастично поддерживаетсяНе поддерживается
Переименование столбцов в результирующем набореЧастично поддерживаетсяНе поддерживается
SQL с несколькими операторамиНе поддерживаетсяНедоступно
Именованные параметры запросаПоддерживаетсяНе поддерживается (отсутствует в спецификации JDBC)
Потоковая передача данных через PreparedStatementПоддерживаетсяНе поддерживается
  • JDBC V2 реализован в более легковесном варианте, поэтому часть функциональности была удалена.
    • Потоковая передача данных не поддерживается в JDBC V2, так как эта возможность не входит в спецификацию JDBC и Java.
  • JDBC V2 требует явной конфигурации. Механизм failover по умолчанию не используется.
    • Протокол должен быть указан в URL. Запрещено неявное определение протокола на основе номера порта.

Изменения конфигурации​

Доступны только два перечисления:

  • com.clickhouse.jdbc.DriverProperties — собственные параметры конфигурации драйвера.
  • com.clickhouse.client.api.ClientConfigProperties — свойства конфигурации клиента. Изменения конфигурации клиента описаны в документации по Java‑клиенту.

Свойства подключения разбираются следующим образом:

  • Сначала свойства извлекаются из URL. Они имеют приоритет над всеми остальными свойствами.
  • Параметры драйвера не передаются клиенту.
  • Endpoints (host, port, protocol) определяются при разборе 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БеззнаковыйТип JDBC (V2)Класс Java (V2)Тип JDBC (V1)Класс Java (V1)
Int8НетTINYINTjava.lang.ByteTINYINTjava.lang.Byte
Int16НетSMALLINTjava.lang.ShortSMALLINTjava.lang.Short
Int32НетINTEGERjava.lang.IntegerINTEGERjava.lang.Integer
Int64НетBIGINTjava.lang.LongBIGINTjava.lang.Long
UInt8ДаOTHERjava.lang.ShortOTHERcom.clickhouse.data.value.UnsignedByte
UInt16ДаOTHERjava.lang.IntegerOTHERcom.clickhouse.data.value.UnsignedShort
UInt32ДаOTHERjava.lang.LongOTHERcom.clickhouse.data.value.UnsignedInteger
UInt64ДаOTHERjava.math.BigIntegerOTHERcom.clickhouse.data.value.UnsignedLong
Int128НетOTHERjava.math.BigIntegerOTHERjava.math.BigInteger
UInt128НетOTHERjava.math.BigIntegerOTHERjava.math.BigInteger
Int256НетOTHERjava.math.BigIntegerOTHERjava.math.BigInteger
UInt256НетOTHERjava.math.BigIntegerOTHERjava.math.BigInteger
Float32НетREALjava.lang.FloatREALjava.lang.Float
Float64НетDOUBLEjava.lang.DoubleDOUBLEjava.lang.Double
Decimal32НетDECIMALjava.math.BigDecimalDECIMALjava.math.BigDecimal
Decimal64НетDECIMALjava.math.BigDecimalDECIMALjava.math.BigDecimal
Decimal128НетDECIMALjava.math.BigDecimalDECIMALjava.math.BigDecimal
Decimal256НетDECIMALjava.math.BigDecimalDECIMALjava.math.BigDecimal
BoolНетBOOLEANjava.lang.BooleanBOOLEANjava.lang.Boolean
StringНетVARCHARjava.lang.StringVARCHARjava.lang.String
FixedStringНетCHARjava.lang.StringCHARjava.lang.String
DateДаDATEjava.sql.DateDATEjava.time.LocalDate
Date32ДаDATEjava.sql.DateDATEjava.time.LocalDate
DateTimeДаTIMESTAMPjava.sql.TimestampTIMESTAMPjava.time.OffsetDateTime
DateTime64ДаTIMESTAMPjava.sql.TimestampTIMESTAMPjava.time.OffsetDateTime
UUIDНетOTHERjava.util.UUIDOTHERjava.util.UUID
IPv4НетOTHERjava.net.Inet4AddressOTHERjava.net.Inet4Address
IPv6НетOTHERjava.net.Inet6AddressOTHERjava.net.Inet6Address
  • Беззнаковые типы сопоставляются с типами Java для повышения переносимости.
  • Date и Date32 сопоставляются с java.sql.Date для лучшей совместимости с JDBC. Однако java.time.LocalDate можно получить с помощью ResultSet.getObject(int, Class<T>), передав java.time.LocalDate.class в качестве второго аргумента.
  • Array сопоставляется с объектом java.sql.Array.
  • Tuple отображается в объект java.sql.Struct, но также может использоваться как Array.

clickhouse-jdbc реализует стандартный интерфейс JDBC. Будучи построенным на основе clickhouse-client, он предоставляет дополнительные возможности, такие как пользовательское сопоставление типов, поддержка транзакций и стандартные синхронные команды UPDATE и DELETE, что позволяет легко использовать его с устаревшими приложениями и инструментами.

Примечание

Последняя версия JDBC (0.7.2) использует Client-V1

API clickhouse-jdbc является синхронным и, как правило, имеет больше накладных расходов (например, парсинг SQL и маппинг/преобразование типов и т. д.). Используйте clickhouse-client, когда производительность критична или если вы предпочитаете более прямой способ доступа к ClickHouse.

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

  • OpenJDK версии 8 или выше

Настройка​

<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.7.2</version>
    <!-- используйте uber-jar, включающий все зависимости; для меньшего по размеру jar измените classifier на http -->
    <classifier>shaded-all</classifier>
</dependency>

Начиная с версии 0.5.0 используется Apache HTTP Client, встроенный в клиент. Поскольку общая версия пакета отсутствует, необходимо добавить логгер в качестве зависимости.

<!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-api -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.16</version>
</dependency>

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

Класс драйвера: 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

Свойства соединения:

СвойствоЗначение по умолчаниюОписание
continueBatchOnErrorfalseОпределяет, нужно ли продолжать обработку пакета при возникновении ошибки
createDatabaseIfNotExistfalseОпределяет, нужно ли создавать базу данных, если она не существует
custom_http_headersнастраиваемые HTTP-заголовки, разделённые запятыми, например: User-Agent=client1,X-Gateway-Id=123
custom_http_paramsпользовательские параметры HTTP-запроса, разделённые запятыми, например: extremes=0,max_result_rows=100
nullAsDefault00 - обрабатывать значение NULL как есть и генерировать исключение при вставке NULL в столбец без типа Nullable; 1 - обрабатывать значение NULL как есть и отключать проверку на NULL при вставке; 2 - заменять NULL на значение по умолчанию соответствующего типа данных как для запроса, так и для вставки
jdbcCompliancetrueОпределяет, нужно ли поддерживать стандартные синхронные операции UPDATE/DELETE и псевдотранзакции
typeMappingsНастройка сопоставления между типом данных ClickHouse и классом Java, что повлияет на результат как getColumnType(), так и getObject(Class<>?>). Например: UInt128=java.lang.String,UInt256=java.lang.String
wrapperObjectfalseОпределяет, должен ли getObject() возвращать java.sql.Array / java.sql.Struct для типов Array / Tuple.

Примечание: дополнительную информацию см. в разделе конфигурация JDBC.

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

Драйвер JDBC поддерживает те же форматы данных, что и клиентская библиотека.

Примечание
  • AggregatedFunction — ⚠️ не поддерживает SELECT * FROM table ...
  • Decimal — SET output_format_decimal_trailing_zeros=1 в 21.9+ для единообразия
  • Enum — может трактоваться и как строка, и как целое число
  • UInt64 — сопоставляется с long (в client-v1)

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

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()) {
        // ...
    }
}

Insert​

Примечание
  • Используйте 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
}

Вставка с плейсхолдерами​

Этот вариант рекомендуется только для небольших вставок, поскольку потребуется длинное SQL-выражение (которое будет разбираться на стороне клиента и потреблять ресурсы процессора и памяти):

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-библиотеки​

JDBC-коннектор ClickHouse поддерживает три HTTP-библиотеки: HttpClient, HttpURLConnection и Apache HttpClient.

Примечание

HttpClient поддерживается только в JDK 11 и выше.

Драйвер JDBC по умолчанию использует HttpClient. Вы можете изменить HTTP-библиотеку, используемую коннектором JDBC для ClickHouse, задав следующее свойство:

properties.setProperty("http_connection_provider", "APACHE_HTTP_CLIENT");

Полный список соответствующих значений:

Значение свойстваHTTP-библиотека
HTTP_CLIENTHttpClient
HTTP_URL_CONNECTIONHttpURLConnection
APACHE_HTTP_CLIENTApache HttpClient

Подключение к ClickHouse по SSL​

Для установки защищенного JDBC-соединения с ClickHouse через SSL необходимо настроить свойства JDBC, включив в них параметры SSL. Как правило, это требует указания таких свойств SSL, как sslmode и sslrootcert, в JDBC URL или объекте Properties.

Свойства SSL​

ИмяЗначение по умолчаниюДопустимые значенияОписание
sslfalsetrue, falseВключать ли SSL/TLS для соединения
sslmodestrictstrict, noneПроверять ли сертификат SSL/TLS
sslrootcertПуть к корневым сертификатам SSL/TLS
sslcertПуть к сертификату SSL/TLS
sslkeyКлюч RSA в формате PKCS#8
key_store_typeJKS, 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]

Эти ошибки могут нарушить процесс вставки данных и повлиять на стабильность системы. Чтобы устранить эту проблему, необходимо настроить несколько параметров таймаута в операционной системе клиента.

macOS​

В 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 одних только эквивалентных настроек может быть недостаточно для решения проблемы. Необходимы дополнительные действия из-за особенностей обработки параметров keep-alive для сокетов в Linux. Выполните следующие действия:

  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 секунд)
  1. После изменения параметров ядра примените их, выполнив следующую команду:
sudo sysctl -p

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

properties.setProperty("socket_keepalive", "true");
Примечание

В настоящее время для настройки socket keep-alive необходимо использовать библиотеку Apache HTTP Client, так как две другие HTTP-клиентские библиотеки, поддерживаемые clickhouse-java, не позволяют настраивать параметры сокетов. Подробное руководство см. в разделе Настройка HTTP-библиотеки.

Также можно добавить эквивалентные параметры в JDBC URL.

Время ожидания сокета и подключения по умолчанию для драйвера JDBC составляет 30 секунд. Время ожидания можно увеличить для поддержки операций вставки больших объемов данных. Используйте метод options объекта ClickHouseClient вместе с параметрами SOCKET_TIMEOUT и CONNECTION_TIMEOUT, определенными в ClickHouseClientOption:

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();
}