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

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.8</version>
    <classifier>all</classifier>
</dependency>

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

Настройка​

Класс драйвера: 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_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.
remember_last_set_rolestrueЗапоминать последние установленные роли для соединения.
Настройки сервера

Все настройки сервера должны иметь префикс 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 jdbc-v2/0.9.7 clickhouse-java-v2/0.9.6 (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4

Примечание: Рекомендуется использовать формат app_name/version для свойства client_name, поскольку это помогает идентифицировать приложение в журнале запросов.

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

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
Int8TINYINTjava.lang.Byte
Int16SMALLINTjava.lang.Short
Int32INTEGERjava.lang.Integer
Int64BIGINTjava.lang.Long
Int128NUMERICjava.math.BigInteger
Int256NUMERICjava.math.BigInteger
UInt8SMALLINTjava.lang.Short
UInt16INTEGERjava.lang.Integer
UInt32BIGINTjava.lang.Long
UInt64NUMERICjava.math.BigInteger
UInt128NUMERICjava.math.BigInteger
UInt256NUMERICjava.math.BigInteger
Float32FLOATjava.lang.Float
Float64DOUBLEjava.lang.Double
Decimal32DECIMALjava.math.BigDecimal
Decimal64DECIMALjava.math.BigDecimal
Decimal128DECIMALjava.math.BigDecimal
Decimal256DECIMALjava.math.BigDecimal
BoolBOOLEANjava.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
StringVARCHARjava.lang.String
FixedStringVARCHARjava.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
Enum8VARCHARjava.lang.String
Enum16VARCHARjava.lang.String
  • Enum8 и Enum16 по умолчанию сопоставляются с типом java.lang.String.
  • Значения Enum можно считывать как числовые значения, используя соответствующий метод‑геттер или метод getObject(columnIndex, Integer.class).
  • Enum16 внутренне сопоставляется с типом short, а Enum8 — с типом byte. Чтение Enum16 как byte следует избегать из‑за риска повреждения данных.
  • Значения Enum в PreparedStatement можно задавать как строки или числа.

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

Тип ClickHouseТип JDBCКласс Java
DateDATEjava.sql.Date
Date32DATEjava.sql.Date
DateTimeTIMESTAMPjava.sql.Timestamp
DateTime64TIMESTAMPjava.sql.Timestamp
TimeTIMEjava.sql.Time
Time64TIMEjava.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
ArrayARRAYjava.sql.Array
TupleOTHERcom.clickhouse.data.Tuple
MapOTHERjava.util.Map
NestedARRAYjava.sql.Array
  • Array по умолчанию сопоставляется с java.sql.Array для совместимости с JDBC. Это также позволяет получить больше информации о возвращаемом значении массива, что полезно для вывода типов.
  • Array реализует метод getResultSet(), который возвращает java.sql.ResultSet с тем же содержимым, что и исходный массив.
  • Типы коллекций не следует считывать как java.lang.String, поскольку это некорректный способ представления данных (например, строковые значения в массиве не заключаются в кавычки).
  • Map сопоставляется с OTHER, поскольку значение можно получить только с помощью метода getObject(columnIndex, Class<T>).
    • Map не является java.sql.Struct, поскольку в нём нет именованных столбцов.
  • Tuple сопоставляется с Object[], так как может содержать значения разных типов, а использование List недопустимо.
  • Tuple можно прочитать как Array, используя метод getObject(columnIndex, Array.class). В этом случае Array#baseTypeName вернёт определение столбца Tuple.

Метаданные типа элементов массива

Array.getBaseTypeName() возвращает имя типа элемента ClickHouse; Array.getBaseType() возвращает код типа JDBC. JDBC V2 сохраняет полные сигнатуры типов (типы-обёртки, параметры типов), которые V1 отбрасывает.

Общие правила сопоставления для массивов:

Тип ClickHousegetBaseTypeName()getBaseType()
Array(<Примитивный тип>)<Примитивный тип><Примитивный тип JDBC>
Array(<Parameterized Type>(<N>))<Параметризованный тип>(<N>)<JDBC-тип базового типа>
Array(Nullable(<Type>))Nullable(<Type>)<JDBC-тип внутреннего типа>
Array(LowCardinality(<Type>))LowCardinality(<Type>)<тип JDBC внутреннего Type>
Array(Array(...(<Type>)))<Type> (наиболее вложенный элемент)<тип JDBC самого внутреннего типа>
Array(Tuple(...))Tuple(...) (полное определение)OTHER
Array(Enum8(...)) / Array(Enum16(...))Enum8(...) / Enum16(...) (полное определение)VARCHAR

Notes on the rules above:

  • Типы-обёртки (Nullable, LowCardinality) сохраняются в getBaseTypeName(), но getBaseType() возвращает JDBC-код вложенного типа.
  • В метаданных вложенные массивы разворачиваются: getBaseTypeName() возвращает тип самого внутреннего элемента, не являющегося массивом, а не тип непосредственного дочернего элемента.
  • Параметризованные типы (FixedString(N), полные определения Enum/Tuple) сохраняют параметры в getBaseTypeName().

Примеры:

Тип ClickHouse (Пример)getBaseTypeName()getBaseType()
Array(Int8)Int8TINYINT
Array(Int16)Int16SMALLINT
Array(Int32)Int32INTEGER
Array(Int64)Int64BIGINT
Array(UInt8)UInt8SMALLINT
Array(UInt16)UInt16INTEGER
Array(UInt32)UInt32BIGINT
Array(UInt64)UInt64NUMERIC
Array(Float32)Float32FLOAT
Array(Float64)Float64DOUBLE
Array(String)StringVARCHAR
Array(FixedString(8))FixedString(8)VARCHAR
Array(Bool)BoolBOOLEAN
Array(Date)DateDATE
Array(DateTime)DateTimeTIMESTAMP
Array(UUID)UUIDOTHER
Array(Nullable(Int32))Nullable(Int32)INTEGER
Array(Nullable(String))Nullable(String)VARCHAR
Array(LowCardinality(String))LowCardinality(String)VARCHAR
Array(LowCardinality(Nullable(String)))LowCardinality(Nullable(String))VARCHAR
Array(Array(Int32))Int32INTEGER
Array(Array(Array(String)))StringVARCHAR
Array(Tuple(name String, val Int32))Tuple(name String, val Int32)OTHER
Array(Enum8('alpha' = 1, 'beta' = 2, 'gamma' = 3))Enum8('alpha' = 1, 'beta' = 2, 'gamma' = 3)VARCHAR
  • В V2 метод getBaseTypeName() сохраняет полную сигнатуру типа, включая типы-обёртки (Nullable, LowCardinality) и параметры типа (FixedString(8), полные определения Enum и Tuple). В V1 всё это отбрасывается, и возвращается только имя базового типа.
  • Массивы Tuple используют OTHER (1111) в V2 вместо STRUCT (2002), поскольку кортежи в ClickHouse имеют именованные поля, а java.sql.Struct их не поддерживает.
  • Для массивов UUID в V2 используется OTHER (1111), как и для скалярного UUID.
  • Enum сопоставляется с VARCHAR — элементы перечисления идентифицируются по строковому имени независимо от базовой числовой кодировки.

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

Используйте 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.collections.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
PointOTHERdouble[]
RingOTHERdouble[][]
PolygonOTHERdouble[][][]
MultiPolygonOTHERdouble[][][][]

Типы Nullable и LowCardinality

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

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

Тип ClickHouseТип JDBCКласс Java
UUIDOTHERjava.util.UUID
IPv4OTHERjava.net.Inet4Address
IPv6OTHERjava.net.Inet6Address
JSONOTHERjava.lang.String
AggregateFunctionOTHER(двоичное представление)
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 и временных меток.

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

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

Пример:

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 Class (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
Int128✅NUMERICjava.math.BigIntegerNUMERICjava.math.BigInteger
Int256✅NUMERICjava.math.BigIntegerNUMERICjava.math.BigInteger
UInt8❌SMALLINTjava.lang.ShortSMALLINTcom.clickhouse.data.value.UnsignedByte
UInt16❌INTEGERjava.lang.IntegerINTEGERcom.clickhouse.data.value.UnsignedShort
UInt32❌BIGINTjava.lang.LongBIGINTcom.clickhouse.data.value.UnsignedInteger
UInt64❌NUMERICjava.math.BigIntegerNUMERICcom.clickhouse.data.value.UnsignedLong
UInt128✅NUMERICjava.math.BigIntegerNUMERICjava.math.BigInteger
UInt256✅NUMERICjava.math.BigIntegerNUMERICjava.math.BigInteger
Float32✅FLOATjava.lang.FloatFLOATjava.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
  • Основное отличие заключается в том, что беззнаковые числовые типы сопоставляются со стандартными типами Java для повышения переносимости.

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

Тип ClickHouseСовместимо с V1Тип JDBC (V2)Класс Java (V2)Тип JDBC (V1)Класс Java (V1)
String✅VARCHARjava.lang.StringVARCHARjava.lang.String
FixedString✅VARCHARjava.lang.StringVARCHARjava.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❌DATEjava.sql.DateDATEjava.time.LocalDate
Date32❌DATEjava.sql.DateDATEjava.time.LocalDate
DateTime❌TIMESTAMPjava.sql.TimestampTIMESTAMP_WITH_TIMEZONEjava.time.OffsetDateTime
DateTime64❌TIMESTAMPjava.sql.TimestampTIMESTAMP_WITH_TIMEZONEjava.time.OffsetDateTime
Time✅TIMEjava.sql.Timeновый тип / не поддерживаетсяновый тип / не поддерживается
Time64✅TIMEjava.sql.Timeновый тип / не поддерживаетсяновый тип / не поддерживается
  • Time и Time64 поддерживаются в V2 только как новые типы.
  • DateTime и DateTime64 сопоставляются с java.sql.Timestamp для повышения совместимости с JDBC.

Типы Enum

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

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

Тип ClickHouseСовместимо с V1Тип JDBC (V2)Класс Java (V2)Тип JDBC (V1)Класс Java (V1)
Array❌ARRAYjava.sql.ArrayARRAYObject[] или массив примитивных типов
Кортеж❌OTHERObject[]STRUCTjava.sql.Struct
Map❌JAVA_OBJECTjava.util.MapSTRUCTjava.util.Map
Nested❌ARRAYjava.sql.ArraySTRUCTjava.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✅OTHERdouble[]OTHERdouble[]
Ring✅OTHERdouble[][]OTHERdouble[][]
Polygon✅OTHERdouble[][][]OTHERdouble[][][]
MultiPolygon✅OTHERdouble[][][][]OTHERdouble[][][][]

Типы Nullable и LowCardinality

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

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

Тип ClickHouseСовместимо с V1Тип JDBC (V2)Класс Java (V2)Тип JDBC (V1)Java Class (V1)
JSON❌OTHERjava.lang.Stringне поддерживаетсяне поддерживается
AggregateFunction✅OTHER(двоичное представление)OTHER(двоичное представление)
SimpleAggregateFunction✅(тип-обёртка)(класс-обёртка)(тип-обёртка)(класс-обёртка)
UUID✅OTHERjava.util.UUIDVARCHARjava.util.UUID
IPv4✅OTHERjava.net.Inet4AddressVARCHARjava.net.Inet4Address
IPv6✅OTHERjava.net.Inet6AddressVARCHARjava.net.Inet6Address
Dynamic❌OTHERjava.Objectне поддерживаетсяне поддерживается
Variant❌OTHERjava.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.

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

Настройка​

<!-- 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, упакованный вместе с клиентом. Поскольку у этого пакета нет общей (shared) версии, необходимо добавить библиотеку для логирования в качестве зависимости.

<!-- 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 в столбец, не допускающий NULL; 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()) {
        // ...
    }
}

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

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

Примечание

Прямое двоичное чтение состояния AggregateFunction поддерживается только для groupBitmap. Для других агрегатных функций (min, max, avg и т. д.) используйте комбинаторы -Merge в запросе (например, SELECT minMerge(min_state) FROM ...), чтобы разрешить состояние агрегации на стороне сервера и получить обычное значение.

// 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, в URL JDBC или объекте 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]

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

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