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

Gradle (Kotlin)

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

Gradle

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

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

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

Примечание

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

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

Синтаксис URL: jdbc:(ch|clickhouse)[:<protocol>]://endpoint[:port][/<database>][?param1=value1&param2=value2][#tag1,tag2,...], например:

• jdbc:clickhouse:http://localhost:8123
• jdbc:clickhouse:https://localhost:8443?ssl=true

Обратите внимание на следующие особенности синтаксиса URL:

• В URL допускается только одна конечная точка
• протокол следует указывать, если используется не значение по умолчанию — 'HTTP'
• порт следует указывать, если используется порт, отличный от порта по умолчанию '8123'
• драйвер не определяет протокол по номеру порта; его необходимо указывать явно
• Параметр ssl не требуется, если протокол указан.

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

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

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

Свойство	Значение по умолчанию	Описание
disable_frameworks_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.

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

Все настройки сервера должны иметь префикс 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 или свойств не требуется — они будут закодированы автоматически.

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

Драйвер 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.

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

Тип 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	Object[]
Map	JAVA_OBJECT	java.util.Map

• 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.

Геотипы

Тип 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).

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

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

Date vs DateTime

Date хранится без часового пояса, тогда как DateTime хранится с часовым поясом. Это может привести к неожиданным результатам при неосторожном использовании.

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

String url = "jdbc:ch://my-server:8123/system";

Properties properties = new Properties();
DataSource dataSource = new DataSource(url, properties);//DataSource or DriverManager are the main entry points
try (Connection conn = dataSource.getConnection()) {
... // do something with the connection

Предоставление учётных данных и настроек

String url = "jdbc:ch://localhost:8123?jdbc_ignore_unsupported_values=true&socket_timeout=10";

Properties info = new Properties();
info.put("user", "default");
info.put("password", "password");
info.put("database", "some_db");

//Creating a connection with DataSource
DataSource dataSource = new DataSource(url, info);
try (Connection conn = dataSource.getConnection()) {
... // do something with the connection
}

//Alternate approach using the DriverManager
try (Connection conn = DriverManager.getConnection(url, info)) {
... // do something with the connection
}

Простое выражение

try (Connection conn = dataSource.getConnection(...);
    Statement stmt = conn.createStatement()) {
    ResultSet rs = stmt.executeQuery("select * from numbers(50000)");
    while(rs.next()) {
        // ...
    }
}

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

try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (?, ?)")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.addBatch();
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

HikariCP

// connection pooling won't help much in terms of performance,
// because the underlying implementation has its own pool.
// for example: HttpURLConnection has a pool for sockets
HikariConfig poolConfig = new HikariConfig();
poolConfig.setConnectionTimeout(5000L);
poolConfig.setMaximumPoolSize(20);
poolConfig.setMaxLifetime(300_000L);
poolConfig.setDataSource(new ClickHouseDataSource(url, properties));

try (HikariDataSource ds = new HikariDataSource(poolConfig);
     Connection conn = ds.getConnection();
     Statement s = conn.createStatement();
     ResultSet rs = s.executeQuery("SELECT * FROM system.numbers LIMIT 3")) {
    while (rs.next()) {
        // handle row
        log.info("Integer: {}, String: {}", rs.getInt(1), rs.getString(1));//Same column but different types
    }
}

Дополнительная информация

Дополнительную информацию см. в нашем репозитории GitHub и документации Java-клиента.

Устранение неполадок

Логирование

Драйвер использует slf4j для ведения журнала и будет использовать первую доступную реализацию в classpath.

Устранение таймаута JDBC при больших вставках данных

При выполнении больших вставок в ClickHouse с длительным временем выполнения могут возникать ошибки тайм-аута JDBC, такие как:

Caused by: java.sql.SQLException: Read timed out, server myHostname [uri=https://hostname.aws.clickhouse.cloud:8443]

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

macOS

В macOS можно настроить следующие параметры для решения проблемы:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1

Linux

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

1. Настройте следующие параметры ядра Linux в /etc/sysctl.conf или соответствующем конфигурационном файле:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1
• net.ipv4.tcp_keepalive_intvl: 75
• net.ipv4.tcp_keepalive_probes: 9
• net.ipv4.tcp_keepalive_time: 60 (можно рассмотреть возможность уменьшения этого значения по сравнению со значением по умолчанию — 300 секунд)

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; они имеют приоритет над всеми остальными свойствами.
• Свойства драйвера не передаются клиенту.
• Endpoints (host, port, protocol) извлекаются из URL.

Пример:

String url = "jdbc:ch://my-server:8443/default?" +
            "jdbc_ignore_unsupported_values=true&" +
            "socket_rcvbuf=800000";

Properties properties = new Properties();
properties.setProperty("socket_rcvbuf", "900000");
try (Connection conn = DriverManager.getConnection(url, properties)) {
    // Connection will use socket_rcvbuf=800000 and jdbc_ignore_unsupported_values=true
    // Endpoints: my-server:8443 protocol: http (not secure)
    // Database: default
}

Изменения типов данных

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

Тип в ClickHouse	Совместимость с 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.

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

Тип 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

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

Геотипы

Тип 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.Object	Не поддерживается	Не поддерживается
Variant	❌	OTHER	java.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, встроенный в клиент. Поскольку общая версия пакета отсутствует, необходимо добавить логгер в качестве зависимости.

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 в столбец без типа 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 function doc по возможности

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

Этот вариант рекомендуется только для небольших вставок, поскольку потребуется длинное 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, в JDBC URL или объекте 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]

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

macOS

В macOS можно настроить следующие параметры для решения проблемы:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1

Linux

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

1. Настройте следующие параметры ядра Linux в /etc/sysctl.conf или другом соответствующем конфигурационном файле:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1
• net.ipv4.tcp_keepalive_intvl: 75
• net.ipv4.tcp_keepalive_probes: 9
• net.ipv4.tcp_keepalive_time: 60 (можно рассмотреть уменьшение этого значения по сравнению со значением по умолчанию — 300 секунд)

2. После изменения параметров ядра примените их, выполнив следующую команду:

sudo sysctl -p

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

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

Примечание

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

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

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

final int MS_12H = 12 * 60 * 60 * 1000; // 12 h in ms
final String sql = "insert into table_a (c1, c2, c3) select c1, c2, c3 from table_b;";

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP)) {
    client.read(servers).write()
        .option(ClickHouseClientOption.SOCKET_TIMEOUT, MS_12H)
        .option(ClickHouseClientOption.CONNECTION_TIMEOUT, MS_12H)
        .query(sql)
        .executeAndWait();
}