JDBC-драйвер

v0.8+

Примечание

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

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

• OpenJDK версии >= 8

Настройка

Maven

<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.9.7</version>
    <classifier>all</classifier>
</dependency>

Gradle (Kotlin)

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation("com.clickhouse:clickhouse-jdbc:0.9.7:all")

Gradle

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation 'com.clickhouse:clickhouse-jdbc:0.9.7:all'

Если вы используете драйвер JDBC в приложении, которое требует добавления JAR-файла в classpath, вам необходимо скачать JAR-файл по следующему адресу:

• Maven Central и добавьте его в classpath
  • начиная с версии 0.9.4 доступен артефакт https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all
  • используйте квалификатор all, чтобы получить JAR‑файл, включающий все shaded‑зависимости.
• или из официального репозитория — отсюда

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

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

Примечание

com.clickhouse.jdbc.ClickHouseDriver — это класс‑фасад для новой и старой реализаций JDBC. По умолчанию используется новая реализация JDBC. Вы можете использовать старую реализацию JDBC, установив системное свойство clickhouse.jdbc.v1 в значение true. Это свойство должно быть установлено до обращения к классу Driver.

Альтернативный способ переключаться между версиями — напрямую использовать классы Driver каждой версии:

• com.clickhouse.jdbc.Driver — новая реализация JDBC (V2).
• com.clickhouse.jdbc.DriverV1 — старая реализация JDBC (V1).

Синтаксис 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_detection	true	Отключить определение фреймворков по заголовку User-Agent
jdbc_ignore_unsupported_values	false	Подавляет SQLFeatureNotSupportedException в случаях, когда это не влияет на работу драйвера
clickhouse.jdbc.v1	false	Использовать старую реализацию JDBC вместо новой
default_query_settings	null	Позволяет передавать значения настроек запроса по умолчанию при выполнении запросов
jdbc_resultset_auto_close	true	Автоматически закрывает ResultSet при закрытии Statement
beta.row_binary_for_simple_insert	false	Использовать реализацию PreparedStatement, основанную на записи в формате RowBinary. Работает только для запросов INSERT INTO ... VALUES.
jdbc_resultset_auto_close	true	Автоматически закрывает ResultSet при закрытии Statement
jdbc_use_max_result_rows	false	Позволяет использовать серверное свойство max_result_rows для ограничения числа строк, возвращаемых запросом. При включении переопределяет режим переполнения, заданный пользователем. Подробности см. в JavaDoc.
jdbc_sql_parser	JAVACC	Определяет, какой SQL‑парсер использовать. Доступные варианты: ANTLR4, ANTLR4_PARAMS_PARSER, JAVACC.
remember_last_set_roles	true	Запоминает последние назначенные роли для соединения.

Настройки сервера

Все настройки сервера должны иметь префикс 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);

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

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, ни свойства — это будет сделано автоматически.

Идентификация клиента

Существует два способа идентифицировать приложение, инициировавшее запрос: задать com.clickhouse.client.api.ClientConfigProperties#CLIENT_NAME через свойства соединения или использовать метод java.sql.Connection#setClientInfo(String name, String value).

Properties properties = new Properties();
properties.setProperty(ClientConfigProperties.CLIENT_NAME.getKey(), "my-app-01");
Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);

conn.setClientInfo(com.clickhouse.jdbc.ClientInfoProperties.APPLICATION_NAME.getKey(), "my-app-01");

Оба способа приведут к следующему значению http_user_agent в журнале запросов:

my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4

Идентификация операции

Драйвер JDBC генерирует query_id для каждой операции (в настоящее время он добавляется в исключения, генерируемые сервером).

Чтобы задать log_comment для операции, используйте метод com.clickhouse.jdbc.StatementImpl#getLocalSettings. Для этого необходимо предварительно привести Statement или PreparedStatement к типу com.clickhouse.jdbc.StatementImpl.

StatementImpl stmt = (StatementImpl) conn.createStatement();
stmt.getLocalSettings().logComment("some-comment");

Примечание: этот подход работает только при однопоточном использовании Statement, поскольку localSettings являются общими для всех потоков.

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

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

Сопоставление типов JDBC

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

• ResultSet#getObject(columnIndex) — метод вернёт объект соответствующего класса Java. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short и т. д.)
• ResultSetMetaData#getColumnType(columnIndex) — метод вернёт соответствующий тип JDBC. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short и т. д.)

Существует несколько способов изменить сопоставление:

• ResultSet#getObject(columnIndex, class) — метод попытается привести значение к типу class. Для таких преобразований существуют определённые ограничения. Подробности см. в соответствующих разделах.

Числовые типы

Тип ClickHouse	Тип JDBC	Класс Java
Int8	TINYINT	java.lang.Byte
Int16	SMALLINT	java.lang.Short
Int32	INTEGER	java.lang.Integer
Int64	BIGINT	java.lang.Long
Int128	OTHER	java.math.BigInteger
Int256	OTHER	java.math.BigInteger
UInt8	OTHER	java.lang.Short
UInt16	OTHER	java.lang.Integer
UInt32	OTHER	java.lang.Long
UInt64	OTHER	java.math.BigInteger
UInt128	OTHER	java.math.BigInteger
UInt256	OTHER	java.math.BigInteger
Float32	REAL	java.lang.Float
Float64	DOUBLE	java.lang.Double
Decimal32	DECIMAL	java.math.BigDecimal
Decimal64	DECIMAL	java.math.BigDecimal
Decimal128	DECIMAL	java.math.BigDecimal
Decimal256	DECIMAL	java.math.BigDecimal
Bool	BOOLEAN	java.lang.Boolean

• Числовые типы взаимно конвертируемы. Поэтому значение типа Int8 можно получить как Float64 и наоборот:
  • rs.getObject(1, Float64.class) вернёт значение типа Float64 из столбца Int8.
  • rs.getLong(1) вернёт значение типа Long из столбца Int8.
  • rs.getByte(1) может вернуть значение типа Byte из столбца Int16, если оно попадает в диапазон Byte.
• Преобразование из более широкого типа данных в более узкий не рекомендуется из‑за риска повреждения данных.
• Тип Bool также ведёт себя как числовой тип.
• Все числовые типы можно читать как java.lang.String.
• Существует проблема с сохранением значения Float.MAX_VALUE из Java как Float (https://github.com/ClickHouse/clickhouse-java/issues/809). Сохранение того же значения как Double решает эту проблему.

Строковые типы

Тип ClickHouse	Тип JDBC	Класс Java
String	VARCHAR	java.lang.String
FixedString	VARCHAR	java.lang.String

• String можно получать только как java.lang.String или byte[].
• FixedString считывается как есть и будет дополнен нулевыми байтами до длины столбца. (Например, FixedString(10) для 'John' будет прочитан как 'John\0\0\0\0\0\0\0\0\0'.)

Типы Enum

Тип ClickHouse	Тип JDBC	Класс Java
Enum8	OTHER	java.lang.String
Enum16	OTHER	java.lang.String

• Enum8 и Enum16 по умолчанию сопоставляются с java.lang.String.
• Значения Enum можно считывать как числовые, используя соответствующий метод‑геттер или метод getObject(columnIndex, Integer.class).
• Enum16 внутренне сопоставляется с типом short, а Enum8 — с типом byte. Чтение Enum16 как byte следует избегать из‑за риска повреждения данных.
• Значения Enum в PreparedStatement можно задавать как строки или числа.

Типы даты и времени

Тип ClickHouse	Тип JDBC	Класс Java
Date	DATE	java.sql.Date
Date32	DATE	java.sql.Date
DateTime	TIMESTAMP	java.sql.Timestamp
DateTime64	TIMESTAMP	java.sql.Timestamp
Time	TIME	java.sql.Time
Time64	TIME	java.sql.Time

• Типы Date / Time сопоставляются с типами java.sql для лучшей совместимости с JDBC. Однако получить значения типов java.time.LocalDate, java.time.LocalDateTime, java.time.LocalTime можно, используя ResultSet#getObject(columnIndex, Class<T>) и передав соответствующий класс в качестве второго аргумента.
  • rs.getObject(1, java.time.LocalDate.class) вернёт значение типа java.time.LocalDate из столбца Date.
  • rs.getObject(1, java.time.LocalDateTime.class) вернёт значение типа java.time.LocalDateTime из столбца DateTime.
  • rs.getObject(1, java.time.LocalTime.class) вернёт значение типа java.time.LocalTime из столбца Time.
• Date, Date32, Time, Time64 не зависят от часового пояса сервера.
• DateTime, DateTime64 зависят от часового пояса сервера или сессии.
• DateTime и DateTime64 можно получить в виде ZonedDateTime, вызвав getObject(colIndex, ZonedDateTime.class).

Вложенные типы

Тип ClickHouse	Тип JDBC	Класс Java
Array	ARRAY	java.sql.Array
Tuple	OTHER	com.clickhouse.data.Tuple
Map	JAVA_OBJECT	java.util.Map
Nested	ARRAY	java.sql.Array

• Array по умолчанию сопоставляется с java.sql.Array для совместимости с JDBC. Это также позволяет получить больше информации о возвращаемом значении массива, что полезно для вывода типов.
• Array реализует метод getResultSet(), который возвращает java.sql.ResultSet с тем же содержимым, что и исходный массив.
• Типы коллекций не следует читать как java.lang.String, так как это некорректный способ представления данных (например, строковые значения в массивах не заключаются в кавычки).
• Map сопоставляется типу JAVA_OBJECT, поскольку значение можно прочитать только с помощью метода getObject(columnIndex, Class<T>).
  • Map не является java.sql.Struct, поскольку в нём нет именованных столбцов.
• Tuple сопоставляется с Object[], поскольку он может содержать элементы разных типов, поэтому использовать List нельзя.
• Tuple можно прочитать как Array, используя метод getObject(columnIndex, Array.class). В этом случае Array#baseTypeName вернёт определение столбца Tuple.

Запись массивов

Используйте java.sql.Connection#createArrayOf для создания объекта java.sql.Array. Этот объект предназначен для унификации работы с массивами в разных базах данных. Соединение требуется, чтобы передать конфигурацию фабричному методу Array.

Метод принимает два аргумента:

• typeName — имя типа элементов массива. Например, Array(Int32) -> "Int32".
• elements — сами элементы массива. Например, [[1, 2, 3], [4, 5, 6]] -> new Integer[][] {{1, 2, 3}, {4, 5, 6}}.

Кортеж можно представить как Object[] или как java.sql.Struct (см. ниже, как записывать кортежи).

Пример

try (Connection conn = ...) {
    Array array = conn.createArrayOf("Int32", new Integer[][] {{1, 2, 3}, {4, 5, 6}});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (arr) VALUES (?)")) {
        ps.setArray(1, array);
        ps.executeUpdate();
    }
}

Чтение массивов

Используйте ResultSet#getArray(columnIndex) для чтения объекта Array. Этот объект можно использовать для доступа к массиву любой глубины вложенности. Метод Array#getResultSet() можно использовать для чтения элементов массива в более унифицированном виде, как java.sql.ResultSet. Это полезно, когда точный тип элементов массива неизвестен.

Пример

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Array(Int32)")) {
        ps.setArray(1, array);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Array array = rs.getArray(1);

                Object[] arr = (Object[]) array;
                Arrays.stream(arr).forEach(this::handleArrayElement);

                // or by using `ResultSet`
                ResultSet resultSet = array.getResultSet();
                while (resultSet.next()) {
                    // ...
                }
            }
        }
    } 
}

Запись кортежей

Кортежи сопоставляются с объектом com.clickhouse.data.Tuple и должны записываться в виде этого объекта с помощью метода setObject(columnIndex, tuple). Для лучшей переносимости можно использовать объект java.sql.Struct для записи кортежей.

Пример

try (Connection conn = ...) {
    Tuple tuple = new Tuple(1, "test", LocalDate.parse("2026-03-02"));
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (tuple) VALUES (?)")) {
        ps.setObject(1, tuple);
        ps.executeUpdate();
    }
}

try (Connection conn = ...) {
    Struct struct = conn.createStruct("Tuple(Int32, String, Date)", new Object[] {1, "test", LocalDate.parse("2026-03-02")});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (tuple) VALUES (?)")) {
        ps.setStruct(1, struct);
        ps.executeUpdate();
    }
}

Чтение кортежей

Метод getObject(columnIndex) возвращает Object[]. Кортежи можно прочитать как java.sql.Array, используя метод getObject(columnIndex, Array.class).

Пример

try (Connection conn = ...) {
    try (PreparedStatement stmt = conn.prepareStatement("SELECT ?::Tuple(String, Int32, Date)")) {
        Array tuple = conn.createArrayOf("Tuple(String, Int32, Date)",  new Object[]{"test", 123, LocalDate.parse("2026-03-02")});
        stmt.setObject(1, tuple);
        try (ResultSet rs = stmt.executeQuery()) {
            rs.next();
            Array dbTuple = rs.getArray(1);
            Assert.assertEquals(dbTuple, tuple);
            Object arr = rs.getObject(1);
            Assert.assertEquals(arr, tuple.getArray());
        }
    }
}

Запись в Map

Map можно записывать только как объект java.collections.Map, поскольку для этого типа требуются пары ключ-значение (java.sql.Struct не поддерживает пары ключ-значение).

Пример

try (Connection conn = ...) {
    Map<String, Integer> map = new HashMap<>();
    map.put("key1", 1);
    map.put("key2", 2);
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (map) VALUES (?)")) {
        ps.setObject(1, map);
        ps.executeUpdate();
    }
}

Чтение типов Map

Map можно получить как объект java.util.Map, используя метод getObject(columnIndex, Map.class).

Пример

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Map(String, Int32)")) {
        ps.setStruct(1, struct);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Map<String, Integer> map = rs.getObject(1, Map.class);
                // ...
            }
        }
    }
}

Запись в Nested

Используйте java.sql.Connection#createStruct для создания экземпляра java.sql.Struct. Этот объект предназначен для унифицированной обработки вложенных структур в различных СУБД. Объект Connection необходим для передачи конфигурации в фабричный метод Struct.

Метод принимает два аргумента:

• typeName — имя типа вложенных элементов. Например, Nested(Tuple(Int32, String)) -> "Nested(Tuple(Int32, String))".
• elements — это сами вложенные элементы. Например [1, 'test'] -> new Object[] {1, 'test'}.

Пример

try (Connection conn = ...) {
    Struct struct = conn.createStruct("Nested(Tuple(Int32, String))", new Object[] {1, 'test'});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (nested) VALUES (?)")) {
        ps.setStruct(1, struct);
        ps.executeUpdate();
    }
}

Чтение вложенных типов

Используйте ResultSet#getStruct(columnIndex, StructDescriptor) для чтения объекта Nested. Этот объект можно использовать для доступа к вложенной структуре произвольной глубины. Метод Struct#getResultSet() можно использовать для чтения вложенных элементов в более унифицированном виде — как java.sql.ResultSet. Это полезно, когда точный тип вложенных элементов заранее неизвестен.

Пример

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Nested(Tuple(Int32, String))")) {
        ps.setStruct(1, struct);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Struct struct = rs.getStruct(1);
                Object[] tuple = (Object[]) struct;
                Arrays.stream(tuple).forEach(this::handleTupleElement);

                // or by using `ResultSet`
                ResultSet resultSet = struct.getResultSet();
                while (resultSet.next()) {
                    // ...
                }
            }
        }
    }
}

Геотипы

Тип ClickHouse	Тип JDBC	Класс Java
Point	OTHER	double[]
Ring	OTHER	double[][]
Polygon	OTHER	double[][][]
MultiPolygon	OTHER	double[][][][]

Типы Nullable и LowCardinality

• Nullable и LowCardinality — это специальные типы-обёртки над другими типами.
• Nullable влияет на то, как ResultSetMetaData возвращает имена типов

Специальные типы

Тип ClickHouse	Тип JDBC	Класс Java
UUID	OTHER	java.util.UUID
IPv4	OTHER	java.net.Inet4Address
IPv6	OTHER	java.net.Inet6Address
JSON	OTHER	java.lang.String
AggregateFunction	OTHER	(двоичное представление)
SimpleAggregateFunction	(тип-обёртка)	(класс-обёртка)

• UUID не является стандартным типом JDBC. Однако он входит в состав JDK. По умолчанию метод getObject() возвращает объект java.util.UUID.
• UUID можно считывать и записывать как String с помощью метода getObject(columnIndex, String.class).
• IPv4 и IPv6 не относятся к стандартным типам JDBC. Однако они входят в стандартную библиотеку JDK. По умолчанию метод getObject() возвращает объекты java.net.Inet4Address и java.net.Inet6Address.
• IPv4 и IPv6 можно считывать и записывать как значения типа String с помощью метода getObject(columnIndex, String.class).

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

Ознакомьтесь с руководством по Date/Time, в котором описаны типичные ошибки и логика работы драйвера при обработке значений Date/Time и Timestamp.

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

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

Вставка данных

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]

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

Mac OS

В 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 одних только эквивалентных настроек может быть недостаточно для устранения проблемы. Из‑за особенностей того, как 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. После изменения параметров ядра примените их, выполнив следующую команду:

sudo sysctl -p

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

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

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

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

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

• JDBC V2 реализован как более лёгкое решение, поэтому часть функциональности была удалена.
  • Потоковая передача данных не поддерживается в JDBC V2, так как потоковая передача не предусмотрена спецификацией JDBC и Java.
• JDBC V2 требует явной конфигурации. Не предоставляет настроек отказоустойчивости по умолчанию.
  • Протокол в URL должен быть указан явно; определение протокола по номеру порта не выполняется.

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

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

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

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

• Сначала из URL разбираются свойства; они переопределяют все остальные.
• Свойства драйвера не передаются клиенту.
• Конечные точки (host, port, protocol) извлекаются из URL.

Example:

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	Совместим с V1	Тип JDBC (V2)	Класс Java (V2)	Тип JDBC (V1)	Класс Java (V1)
Int8	✅	TINYINT	java.lang.Byte	TINYINT	java.lang.Byte
Int16	✅	SMALLINT	java.lang.Short	SMALLINT	java.lang.Short
Int32	✅	INTEGER	java.lang.Integer	INTEGER	java.lang.Integer
Int64	✅	BIGINT	java.lang.Long	BIGINT	java.lang.Long
Int128	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
Int256	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
UInt8	❌	OTHER	java.lang.Short	OTHER	com.clickhouse.data.value.UnsignedByte
UInt16	❌	OTHER	java.lang.Integer	OTHER	com.clickhouse.data.value.UnsignedShort
UInt32	❌	OTHER	java.lang.Long	OTHER	com.clickhouse.data.value.UnsignedInteger
UInt64	❌	OTHER	java.math.BigInteger	OTHER	com.clickhouse.data.value.UnsignedLong
UInt128	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
UInt256	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
Float32	✅	REAL	java.lang.Float	REAL	java.lang.Float
Float64	✅	DOUBLE	java.lang.Double	DOUBLE	java.lang.Double
Decimal32	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal64	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal128	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal256	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Bool	✅	BOOLEAN	java.lang.Boolean	BOOLEAN	java.lang.Boolean

• Основное отличие заключается в том, что беззнаковые числовые типы сопоставляются со стандартными типами Java для повышения переносимости.

Строковые типы

Тип ClickHouse	Совместим с V1	Тип JDBC (V2)	Класс Java (V2)	Тип JDBC (V1)	Класс Java (V1)
String	✅	VARCHAR	java.lang.String	VARCHAR	java.lang.String
FixedString	✅	VARCHAR	java.lang.String	VARCHAR	java.lang.String

• FixedString считывается «как есть» в обеих версиях. Например, FixedString(10) для 'John' будет прочитан как 'John\0\0\0\0\0\0\0\0\0'.
• Когда используется PreparedStatement#setBytes, значение будет преобразовано в unhex('<hex_string>'), а затем прочитано как String.
• Строки хранятся в кодировке UTF-8.

Типы даты и времени

Тип ClickHouse	Совместим с V1	Тип JDBC (V2)	Класс Java (V2)	Тип JDBC (V1)	Класс Java (V1)
Date	❌	DATE	java.sql.Date	DATE	java.time.LocalDate
Date32	❌	DATE	java.sql.Date	DATE	java.time.LocalDate
DateTime	❌	TIMESTAMP	java.sql.Timestamp	TIMESTAMP	java.time.OffsetDateTime
DateTime64	❌	TIMESTAMP	java.sql.Timestamp	TIMESTAMP	java.time.OffsetDateTime
Time	✅	TIME	java.sql.Time	новый тип / не поддерживается	новый тип / не поддерживается
Time64	✅	TIME	java.sql.Time	новый тип / не поддерживается	новый тип / не поддерживается

• Time и Time64 поддерживаются только в V2, так как являются новыми типами.
• DateTime и DateTime64 сопоставляются с java.sql.Timestamp для повышения совместимости с JDBC.

Типы Enum

Тип ClickHouse	Совместимо с V1	Тип JDBC (V2)	Класс Java (V2)	Тип JDBC (V1)	Класс Java (V1)
Enum	✅	VARCHAR	java.lang.String	OTHER	java.lang.String
Enum8	✅	VARCHAR	java.lang.String	OTHER	java.lang.String
Enum16	✅	VARCHAR	java.lang.String	OTHER	java.lang.String

Вложенные типы

Тип ClickHouse	Совместим с V1	Тип JDBC (V2)	Класс Java (V2)	Тип JDBC (V1)	Класс Java (V1)
Array	❌	ARRAY	java.sql.Array	ARRAY	Object[] или массив примитивных типов
Tuple	❌	OTHER	Object[]	STRUCT	java.sql.Struct
Map	❌	JAVA_OBJECT	java.util.Map	STRUCT	java.util.Map
Nested	❌	ARRAY	java.sql.Array	STRUCT	java.sql.Struct

• В V2 тип Array по умолчанию сопоставляется с java.sql.Array для совместимости с JDBC. Это также даёт больше информации о возвращаемом значении массива, что полезно для вывода типов.
• В V2 Array реализует метод getResultSet(), который возвращает java.sql.ResultSet с тем же содержимым, что и исходный массив.
• V1 использует тип STRUCT для Map, но всегда возвращает объект типа java.util.Map. V2 исправляет это, сопоставляя Map с JAVA_OBJECT.
• V1 использует STRUCT для Tuple, но всегда возвращает объект типа List<Object>. V2 сопоставляет Tuple с OTHER и по умолчанию возвращает Object[].
• V2 добавляет com.clickhouse.data.Tuple#Tuple для записи кортежей. Это упрощает определение того, является ли значение кортежем или массивом.
• PreparedStatement#setBytes и ResultSet#getBytes не могут использоваться с типами коллекций. Эти методы предназначены для работы с двоичными строками.
• Обычно для записи и чтения типов Array используется объект java.sql.Array. Драйвер JDBC полностью поддерживает эту возможность.
• V2 Nested сопоставляется с Array и представляется в виде массива кортежей.
• V2 имеет частичную поддержку java.sql.Struct, поскольку он по своей структуре очень похож на тип Array и не поддерживает пары ключ‑значение. Struct можно использовать для записи значений типа Tuple.

Геотипы

Тип ClickHouse	Совместим с V1	Тип JDBC (V2)	Класс Java (V2)	Тип JDBC (V1)	Класс Java (V1)
Point	✅	OTHER	double[]	OTHER	double[]
Ring	✅	OTHER	double[][]	OTHER	double[][]
Polygon	✅	OTHER	double[][][]	OTHER	double[][][]
MultiPolygon	✅	OTHER	double[][][][]	OTHER	double[][][][]

Типы Nullable и LowCardinality

• Nullable и LowCardinality — это специальные типы-обёртки над другими типами.
• В V2 эти типы не изменялись.

Специальные типы

Тип ClickHouse	Совместимо с V1	Тип JDBC (V2)	Класс Java (V2)	Тип JDBC (V1)	Класс Java (V1)
JSON	❌	OTHER	java.lang.String	не поддерживается	не поддерживается
AggregateFunction	✅	OTHER	(двоичное представление)	OTHER	(двоичное представление)
SimpleAggregateFunction	✅	(тип-обёртка)	(класс-обёртка)	(тип-обёртка)	(класс-обёртка)
UUID	✅	OTHER	java.util.UUID	VARCHAR	java.util.UUID
IPv4	✅	OTHER	java.net.Inet4Address	VARCHAR	java.net.Inet4Address
IPv6	✅	OTHER	java.net.Inet6Address	VARCHAR	java.net.Inet6Address
Dynamic	❌	OTHER	java.lang.Object	не поддерживается	не поддерживается
Variant	❌	OTHER	java.lang.Object	не поддерживается	не поддерживается

• V1 использует VARCHAR для UUID, но всегда возвращает объект java.util.UUID. V2 устраняет это, сопоставляя UUID с OTHER и также возвращая объект java.util.UUID.
• V1 использует VARCHAR для IPv4 и IPv6, но всегда возвращает объекты java.net.Inet4Address и java.net.Inet6Address. V2 исправляет это, сопоставляя IPv4 и IPv6 с OTHER и возвращая объекты java.net.Inet4Address и java.net.Inet6Address.
• Dynamic и Variant — новые типы, добавленные в V2. В V1 не поддерживаются.
• Тип JSON основан на типе Dynamic, поэтому он поддерживается только в V2.
• Значения IPv4 и IPv6 можно считывать в виде массива байтов byte[] с помощью метода getBytes(columnIndex). Однако рекомендуется использовать специальные классы для этих типов.
• V2 не поддерживает чтение IP-адресов как числовых значений, поскольку конвертацию лучше выполнять средствами классов InetAddress.

Изменения метаданных базы данных

• В V2 для обозначения баз данных используется только термин Schema. Термин Catalog зарезервирован для будущего использования.
• V2 возвращает false для DatabaseMetaData.supportsTransactions() и DatabaseMetaData.supportsSavepoints(). В будущих версиях это поведение будет изменено.

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

Примечание

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

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

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

• OpenJDK версии >= 8

Настройка

Maven

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

Gradle (Kotlin)

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
// используйте uber-jar, включающий все зависимости; для меньшего по размеру jar измените classifier на http
implementation("com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all")

Gradle

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

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

Maven

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

Gradle (Kotlin)

// https://mvnrepository.com/artifact/org.slf4j/slf4j-api
implementation("org.slf4j:slf4j-api:2.0.16")

Gradle

// https://mvnrepository.com/artifact/org.slf4j/slf4j-api
implementation 'org.slf4j:slf4j-api:2.0.16'

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

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

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

Свойство	Значение по умолчанию	Описание
continueBatchOnError	false	Продолжать ли пакетную обработку при возникновении ошибки
createDatabaseIfNotExist	false	Создавать ли базу данных, если она не существует
custom_http_headers		пользовательские HTTP-заголовки, перечисленные через запятую, например: User-Agent=client1,X-Gateway-Id=123
custom_http_params		пользовательские параметры HTTP-запроса, разделённые запятыми, например: extremes=0,max_result_rows=100
nullAsDefault	0	0 - оставлять значение NULL без изменений и вызывать исключение при попытке вставить NULL в столбец, не допускающий NULL (не Nullable); 1 - оставлять значение NULL без изменений и отключать проверку на NULL при вставке; 2 - заменять NULL на значение по умолчанию для соответствующего типа данных как при выполнении запросов, так и при вставке
jdbcCompliance	true	Следует ли поддерживать стандартные синхронные операции UPDATE/DELETE и псевдотранзакции
typeMappings		Позволяет настроить сопоставление между типом данных ClickHouse и классом Java; это влияет на результат выполнения как getColumnType(), так и getObject(Class<>?>). Например: UInt128=java.lang.String,UInt256=java.lang.String
wrapperObject	false	Определяет, должен ли 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()) {
        // ...
    }
}

Вставка данных

Примечание

• Используйте 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
}

• документацию по функции input по возможности

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

Этот вариант рекомендуется только для небольших вставок, так как для него потребуется длинное 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_CLIENT	HttpClient
HTTP_URL_CONNECTION	HttpURLConnection
APACHE_HTTP_CLIENT	Apache HttpClient

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

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

Свойства SSL

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

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

Mac OS

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

sudo sysctl -p

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

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

Примечание

В настоящее время при включении 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();
}