JDBC-драйвер

v0.8+

Примечание

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

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

OpenJDK версии >= 8

Настройка

Maven
Gradle (Kotlin)
Gradle

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

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

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation 'com.clickhouse:clickhouse-jdbc:0.9.6: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 в параметрах подключения.

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

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

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]

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

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 для сокетов, требуются дополнительные действия. Выполните следующие шаги:

Настройте следующие параметры ядра 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 секунд)

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

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 Type (V2)	Java Class (V2)	JDBC Type (V1)	Java Class (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(). Это поведение будет изменено в последующих версиях.

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

Значение свойства	HTTP-библиотека
HTTP_CLIENT	`HttpClient`
HTTP_URL_CONNECTION	`HttpURLConnection`
APACHE_HTTP_CLIENT	Apache `HttpClient`

Имя	Значение по умолчанию	Допустимые значения	Описание
`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`

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

Настройка​

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

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

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

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

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

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

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

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

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

HikariCP​

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

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

Логирование​

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

Mac OS​

Linux​

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

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

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

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

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

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

Настройка​

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

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

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

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

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

С табличной функцией input​

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

Обработка DateTime и часовых поясов​

Работа с AggregateFunction​

Настройка HTTP-библиотеки​

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

Свойства SSL​

Устранение таймаута JDBC при крупных вставках данных​

Mac OS​

Linux​

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

Настройка

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

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

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

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

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

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

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

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

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

`HikariCP`

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

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

Логирование

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

Mac OS

Linux

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

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

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

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

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

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

Настройка

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

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

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

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

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

С табличной функцией input

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

Обработка DateTime и часовых поясов

Работа с `AggregateFunction`

Настройка HTTP-библиотеки

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

Свойства SSL

Устранение таймаута JDBC при крупных вставках данных

Mac OS

Linux