`clickhouse-jdbc` реализует стандартный интерфейс JDBC на базе новейшего Java-клиента. Если критически важны производительность и прямой доступ, рекомендуем использовать новейший Java-клиент напрямую. Требования к среде * [OpenJDK](https://openjdk.java.net) версии >= 8 Setup ```xml theme={null} {/* https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc */} com.clickhouse clickhouse-jdbc 0.9.8 all ``` ```kotlin theme={null} // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc implementation("com.clickhouse:clickhouse-jdbc:0.9.8:all") ``` ```groovy theme={null} // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc implementation 'com.clickhouse:clickhouse-jdbc:0.9.8:all' ``` Если вы используете JDBC driver в приложении, которое требует добавления jar-файла в classpath, скачайте jar-файл по адресу: * [Maven Central](https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc) и добавьте библиотеку в classpath * начиная с версии `0.9.4` доступен artifact [https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all](https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all) * используйте квалификатор `all`, чтобы получить jar со всеми включёнными затенёнными зависимостями. * или из официального репозитория [по этой ссылке](https://github.com/ClickHouse/clickhouse-java/releases) Конфигурация **Класс драйвера**: `com.clickhouse.jdbc.ClickHouseDriver` `com.clickhouse.jdbc.ClickHouseDriver` — это фасадный класс для новой и старой реализаций JDBC. По умолчанию он использует новую реализацию JDBC. Старую реализацию JDBC можно использовать, установив **system**-свойство `clickhouse.jdbc.v1` в значение `true`. Это свойство нужно установить до обращения к классу Driver. Альтернативный способ переключения между версиями — напрямую использовать классы Driver соответствующей версии: * `com.clickhouse.jdbc.Driver` — новая реализация JDBC (V2). * `com.clickhouse.jdbc.DriverV1` — старая реализация JDBC (V1). **Синтаксис URL**: `jdbc:(ch|clickhouse)[:]://endpoint[:port][/][?param1=value1¶m2=value2][#tag1,tag2,...]`, например: * `jdbc:clickhouse:http://localhost:8123` * `jdbc:clickhouse:https://localhost:8443?ssl=true` Обратите внимание на несколько особенностей синтаксиса URL: * В URL допускается **только** одна конечная точка * протокол следует указывать, если используется не значение по умолчанию — ‘HTTP’ * порт следует указать, если используется не стандартный порт ‘8123’ * драйвер не пытается определить протокол по порту, его нужно указать явно * Параметр `ssl` не требуется, если указан протокол. Свойства подключения Основные параметры конфигурации определены в разделе [Java-клиента](/ru/integrations/language-clients/java/client#client-configuration). Их следует передавать в драйвер без изменений. Драйвер также имеет ряд собственных свойств, не входящих в конфигурацию клиента; они перечислены ниже. **Свойства драйвера**: | Свойство | По умолчанию | Описание | | ----------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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` для ограничения количества строк, возвращаемых запросом. Если параметр включен, он переопределяет заданный пользователем режим overflow. Подробности см. в JavaDoc. | | `jdbc_sql_parser` | `JAVACC` | Определяет, какой SQL-парсер использовать. Возможные значения: `ANTLR4`, `ANTLR4_PARAMS_PARSER`, `JAVACC`. | | `remember_last_set_roles` | `true` | Запоминает последние заданные роли для соединения. | **Настройки сервера** Все настройки сервера должны иметь префикс `clickhouse_setting_` (как и в [конфигурации клиента](/ru/integrations/language-clients/java/client#server-settings)). ```java theme={null} Properties config = new Properties(); config.setProperty("user", "default"); config.setProperty("password", getPassword()); // задать настройку сервера config.put(ClientConfigProperties.serverSetting("allow_experimental_time_time64_type"), "1"); Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", config); ``` **Пример конфигурации**: ```java theme={null} Properties properties = new Properties(); properties.setProperty("user", "default"); properties.setProperty("password", getPassword()); properties.setProperty("client_name", "my-app-01"); // при использовании HTTP-протокола в журнале запросов будет `http_user_agent`, а не `client_name`. Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties); ``` что будет эквивалентно следующему JDBC URL: ```sql theme={null} jdbc:ch:http://localhost:8123/?user=default&password=password&client_name=my-app-01 // учётные данные должны передаваться в `Properties`. Здесь это указано только в качестве примера. ``` Примечание: кодировать JDBC URL или свойства в формате URL не нужно — они будут закодированы автоматически. Идентификация клиента Существует два способа идентифицировать приложение, из которого поступил запрос: задать `com.clickhouse.client.api.ClientConfigProperties#CLIENT_NAME` через параметры подключения или использовать метод `java.sql.Connection#setClientInfo(String name, String value)`. ```java showLineNumbers theme={null} Properties properties = new Properties(); properties.setProperty(ClientConfigProperties.CLIENT_NAME.getKey(), "my-app-01"); Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties); ``` ```java showLineNumbers theme={null} 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 driver генерирует `query_id` для каждой операции (в настоящее время он включён в исключения сервера). Чтобы задать `log_comment` для операции, используйте метод `com.clickhouse.jdbc.StatementImpl#getLocalSettings`. Для этого необходимо сначала привести `Statement` или `PreparedStatement` к типу `com.clickhouse.jdbc.StatementImpl`. ```java showLineNumbers theme={null} StatementImpl stmt = (StatementImpl) conn.createStatement(); stmt.getLocalSettings().logComment("some-comment"); ``` **Примечание:** данный подход работает только для однопоточного использования оператора, так как `localSettings` является общим для всех потоков. Поддерживаемые типы данных JDBC driver поддерживает те же форматы данных, что и базовый [Java-клиент](/ru/integrations/language-clients/java#supported-data-types). Соответствие типов JDBC Следующее соответствие применяется к: * `ResultSet#getObject(columnIndex)` — метод возвращает объект соответствующего класса Java. (`Int8` -> `java.lang.Byte`, `Int16` -> `java.lang.Short`, и т. д.) * `ResultSetMetaData#getColumnType(columnIndex)` — метод возвращает соответствующий тип JDBC. (`Int8` -> `java.lang.Byte`, `Int16` -> `java.lang.Short`, и т. д.) Существует несколько способов изменить соответствие: * `ResultSet#getObject(columnIndex, class)` — метод попытается преобразовать значение к типу `class`. Существуют некоторые ограничения на преобразование. Подробнее см. в соответствующих разделах. **Числовые типы** | Тип ClickHouse | Тип JDBC | Класс Java | | -------------- | -------- | -------------------- | | Int8 | TINYINT | java.lang.Byte | | Int16 | SMALLINT | java.lang.Short | | Int32 | INTEGER | java.lang.Integer | | Int64 | BIGINT | java.lang.Long | | Int128 | OTHER | java.math.BigInteger | | Int256 | OTHER | java.math.BigInteger | | UInt8 | OTHER | java.lang.Short | | UInt16 | OTHER | java.lang.Integer | | UInt32 | OTHER | java.lang.Long | | UInt64 | OTHER | java.math.BigInteger | | UInt128 | OTHER | java.math.BigInteger | | UInt256 | OTHER | java.math.BigInteger | | Float32 | REAL | java.lang.Float | | Float64 | DOUBLE | java.lang.Double | | Decimal32 | DECIMAL | java.math.BigDecimal | | Decimal64 | DECIMAL | java.math.BigDecimal | | Decimal128 | DECIMAL | java.math.BigDecimal | | Decimal256 | DECIMAL | java.math.BigDecimal | | Bool | BOOLEAN | java.lang.Boolean | * числовые типы можно преобразовывать друг в друга. Поэтому `Int8` можно получить как `Float64` и наоборот.: * `rs.getObject(1, Float64.class)` вернёт значение типа `Float64` из столбца `Int8`. * `rs.getLong(1)` вернёт значение типа `Long` из столбца `Int8`. * `rs.getByte(1)` может вернуть значение типа `Byte` из столбца `Int16`, если оно помещается в `Byte`. * Преобразование из более широкого типа в более узкий не рекомендуется из-за риска повреждения данных. * Тип `Bool` также может использоваться как число. * Все числовые типы можно считывать как `java.lang.String`. * При сохранении `Float.MAX_VALUE` из Java как `Float` возникает проблема ([https://github.com/ClickHouse/clickhouse-java/issues/809](https://github.com/ClickHouse/clickhouse-java/issues/809)). Если сохранить то же значение как `Double`, проблема исчезает. **Строковые типы** | Тип ClickHouse | Тип JDBC | Класс Java | | -------------- | -------- | ---------------- | | String | VARCHAR | java.lang.String | | FixedString | VARCHAR | java.lang.String | * `String` можно считывать только как `java.lang.String` или `byte[]`. * `FixedString` считывается как есть и дополняется нулями до длины столбца. (Например, `FixedString(10)` для `'John'` будет считан как `'John\0\0\0\0\0\0\0\0\0'`.) **Типы Enum** | Тип ClickHouse | Тип JDBC | Класс Java | | -------------- | -------- | ---------------- | | Enum8 | OTHER | java.lang.String | | Enum16 | OTHER | java.lang.String | * `Enum8` и `Enum16` по умолчанию соответствуют типу `java.lang.String`. * Значения enum можно считывать как числовые, используя соответствующий геттер или метод `getObject(columnIndex, Integer.class)`. * `Enum16` внутренне представлен как short, а `Enum8` — как byte. Следует избегать чтения `Enum16` как byte из-за риска повреждения данных. * Значения enum можно задавать в `PreparedStatement` как строковые или числовые. **Типы даты/времени** | Тип ClickHouse | Тип JDBC | Класс Java | | -------------- | --------- | ------------------ | | Date | DATE | java.sql.Date | | Date32 | DATE | java.sql.Date | | DateTime | TIMESTAMP | java.sql.Timestamp | | DateTime64 | TIMESTAMP | java.sql.Timestamp | | Time | TIME | java.sql.Time | | Time64 | TIME | java.sql.Time | * Типы Date / Time сопоставляются с типами `java.sql` для лучшей совместимости с JDBC. Однако можно получить `java.time.LocalDate`, `java.time.LocalDateTime` и `java.time.LocalTime`, используя `ResultSet#getObject(columnIndex, Class)` и указав соответствующий класс вторым аргументом. * `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)`. * `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}}`. Tuple может быть представлен как `Object[]` или как `java.sql.Struct` (см. раздел о записи Tuple ниже). **Пример** ```java theme={null} 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`. Это удобно, когда точный тип элементов массива неизвестен. **Пример** ```java theme={null} 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); // или через `ResultSet` ResultSet resultSet = array.getResultSet(); while (resultSet.next()) { // ... } } } } } ``` **Запись Tuple** Значения типа Tuple сопоставляются с объектом `com.clickhouse.data.Tuple` и должны записываться как этот объект с помощью вызова метода `setObject(columnIndex, tuple)`. Для большей переносимости можно использовать объект `java.sql.Struct` для записи значений типа Tuple. **Пример** ```java theme={null} 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(); } } ``` **Чтение Tuple** Метод `getObject(columnIndex)` возвращает `Object[]`. Tuple можно считать как `java.sql.Array` с помощью метода `getObject(columnIndex, Array.class)`. **Пример** ```java theme={null} 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` не поддерживает пары ключ-значение). **Пример** ```java theme={null} try (Connection conn = ...) { Map 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 можно считать как объект `java.collections.Map` с помощью метода `getObject(columnIndex, Map.class)`. **Пример** ```java theme={null} 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 map = rs.getObject(1, Map.class); // ... } } } } ``` **Запись вложенных данных** Используйте `java.sql.Connection#createStruct` для создания экземпляра объекта `java.sql.Struct`. Этот объект предназначен для унификации обработки вложенных структур в различных базах данных. Соединение необходимо для передачи конфигурации в фабричный метод Struct. Метод принимает два аргумента: * `typeName` — имя типа вложенных элементов. Например: `Nested(Tuple(Int32, String))` -> `"Nested(Tuple(Int32, String))"`. * `elements` — сами вложенные элементы. Например, `[1, 'test']` -> `new Object[] {1, 'test'}`. **Пример** ```java theme={null} 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`. Это удобно, когда точный тип вложенных элементов неизвестен. **Пример** ```java theme={null} 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); // или через `ResultSet` ResultSet resultSet = struct.getResultSet(); while (resultSet.next()) { // ... } } } } } ``` **Гео-типы** | Тип ClickHouse | Тип JDBC | Класс Java | | -------------- | -------- | ------------------ | | Point | OTHER | double\[] | | Ring | OTHER | double\[]\[] | | Polygon | OTHER | double\[]\[]\[] | | MultiPolygon | OTHER | double\[]\[]\[]\[] | **Типы Nullable и LowCardinality** * `Nullable` и `LowCardinality` — это специальные типы, которые являются оболочками для других типов. * `Nullable` влияет на то, как в `ResultSetMetaData` возвращаются имена типов **Специальные типы** | Тип ClickHouse | Тип JDBC | Класс Java | | ----------------------- | --------------- | ------------------------ | | UUID | OTHER | java.util.UUID | | IPv4 | OTHER | java.net.Inet4Address | | IPv6 | OTHER | java.net.Inet6Address | | JSON | OTHER | java.lang.String | | AggregateFunction | OTHER | (двоичное представление) | | SimpleAggregateFunction | (обернутый тип) | (класс-обёртка) | * `UUID` не входит в стандарт JDBC. Однако он входит в состав JDK. По умолчанию метод `getObject()` возвращает объект `java.util.UUID`. * `UUID` можно считывать и записывать как `String` с помощью метода `getObject(columnIndex, String.class)`. * `IPv4` и `IPv6` не относятся к стандартным типам JDBC. Однако они входят в JDK. По умолчанию метод `getObject()` возвращает `java.net.Inet4Address` и `java.net.Inet6Address`. * `IPv4` и `IPv6` можно считывать и записывать как `String` с помощью метода `getObject(columnIndex, String.class)`. Работа с датами, временем и часовыми поясами Ознакомьтесь с [руководством по Date/Time](/ru/integrations/language-clients/java/date-time-guide), в котором описаны типичные проблемы и логика работы драйвера при обработке значений Date/Time и временных меток. Создание подключения ```java theme={null} String url = "jdbc:ch://my-server:8123/system"; Properties properties = new Properties(); DataSource dataSource = new DataSource(url, properties);//DataSource или DriverManager — основные точки входа try (Connection conn = dataSource.getConnection()) { ... // выполнить что-то с соединением ``` Передача учётных данных и настроек ```java showLineNumbers theme={null} 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"); //Создание соединения с DataSource DataSource dataSource = new DataSource(url, info); try (Connection conn = dataSource.getConnection()) { ... // выполнить операции с соединением } //Альтернативный подход с использованием DriverManager try (Connection conn = DriverManager.getConnection(url, info)) { ... // выполнить операции с соединением } ``` Простой оператор ```java showLineNumbers theme={null} try (Connection conn = dataSource.getConnection(...); Statement stmt = conn.createStatement()) { ResultSet rs = stmt.executeQuery("select * from numbers(50000)"); while(rs.next()) { // ... } } ``` Вставка ```java showLineNumbers theme={null} try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (?, ?)")) { ps.setString(1, "test"); // идентификатор ps.setObject(2, LocalDateTime.now()); // временная метка ps.addBatch(); ... ps.executeBatch(); // передать всё накопленное в ClickHouse } ``` `HikariCP` ```java showLineNumbers theme={null} // пул соединений не даст большого прироста производительности, // поскольку базовая реализация имеет собственный пул. // например: HttpURLConnection имеет пул для сокетов 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()) { // обработка строки log.info("Integer: {}, String: {}", rs.getInt(1), rs.getString(1));//Один и тот же столбец, но разные типы } } ``` Дополнительная информация Дополнительную информацию см. в нашем [репозитории GitHub](https://github.com/ClickHouse/clickhouse-java) и [документации по Java-клиенту](/ru/integrations/language-clients/java/client). Устранение неполадок Логирование Драйвер использует [slf4j](https://www.slf4j.org/) для логирования и задействует первую доступную реализацию в `classpath`. Устранение тайм-аута JDBC при больших вставках При выполнении больших операций вставки в ClickHouse с длительным временем выполнения могут возникать ошибки тайм-аута JDBC, например: ```plaintext theme={null} Caused by: java.sql.SQLException: Read timed out, server myHostname [uri=https://hostname.aws.clickhouse.cloud:8443] ``` Эти ошибки могут нарушить процесс вставки данных и повлиять на стабильность системы. Для решения этой проблемы может потребоваться скорректировать несколько параметров тайм-аута в ОС клиента. Mac OS В Mac OS для решения этой проблемы можно изменить следующие настройки: * `net.inet.tcp.keepidle`: 60000 * `net.inet.tcp.keepintvl`: 45000 * `net.inet.tcp.keepinit`: 45000 * `net.inet.tcp.keepcnt`: 8 * `net.inet.tcp.always_keepalive`: 1 Linux В Linux одних только аналогичных настроек может оказаться недостаточно для решения проблемы. Из-за различий в том, как Linux обрабатывает настройки keep-alive для сокетов, потребуются дополнительные шаги. Выполните следующие действия: 1. Настройте следующие параметры ядра Linux в `/etc/sysctl.conf` или соответствующем файле конфигурации: * `net.inet.tcp.keepidle`: 60000 * `net.inet.tcp.keepintvl`: 45000 * `net.inet.tcp.keepinit`: 45000 * `net.inet.tcp.keepcnt`: 8 * `net.inet.tcp.always_keepalive`: 1 * `net.ipv4.tcp_keepalive_intvl`: 75 * `net.ipv4.tcp_keepalive_probes`: 9 * `net.ipv4.tcp_keepalive_time`: 60 (При необходимости можно уменьшить это значение по сравнению со значением по умолчанию — 300 секунд) 2. После изменения параметров ядра примените их, выполнив следующую команду: ```shell theme={null} sudo sysctl -p ``` После настройки этих параметров необходимо убедиться, что клиент включает опцию Keep Alive для сокета: ```java theme={null} properties.setProperty("socket_keepalive", "true"); ``` Руководство по миграции Основные изменения | Возможность | V1 (старая) | V2 (новая) | | --------------------------------------------------- | ----------------------- | ------------------------------------------------------- | | Поддержка транзакций | Частично поддерживается | Не поддерживается | | Переименование столбцов в ответе | Частично поддерживается | Не поддерживается | | Многооператорный SQL | Не поддерживается | Не допускается | | Именованные параметры | Поддерживается | Не поддерживается (не предусмотрено спецификацией JDBC) | | Потоковая передача данных через `PreparedStatement` | Поддерживается | Не поддерживается | * JDBC V2 реализован в более облегчённом виде, и некоторые возможности были удалены. * Потоковая передача данных не поддерживается в JDBC V2, поскольку она не предусмотрена спецификацией JDBC и Java. * JDBC V2 требует явной конфигурации. Для аварийного переключения значения по умолчанию не предусмотрены. * Протокол должен быть указан в URL. Не выполняется неявное определение протокола по номеру порта. Изменения конфигурации Существует только два enum-типа: * `com.clickhouse.jdbc.DriverProperties` - собственные параметры конфигурации драйвера. * `com.clickhouse.client.api.ClientConfigProperties` — свойства конфигурации клиента. Изменения в конфигурации клиента описаны в [документации по Java-клиенту](/ru/integrations/language-clients/java/client#migration_from_v1_config). Свойства подключения разбираются следующим образом: * Сначала URL разбирается на свойства. Они имеют приоритет над всеми остальными свойствами. * Свойства драйвера не передаются клиенту. * Параметры конечной точки (хост, порт, протокол) разбираются из URL. Пример: ```java theme={null} 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)) { // Соединение будет использовать socket_rcvbuf=800000 и jdbc_ignore_unsupported_values=true // Конечная точка: my-server:8443 протокол: http (незащищённый) // База данных: 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('')`, а затем считывается как `String`. * Строки хранятся в кодировке UTF-8. **Типы даты/времени** | Тип данных ClickHouse | Совместимость с V1 | Тип JDBC (V2) | Класс Java (V2) | Тип JDBC (V1) | Класс Java (V1) | | --------------------- | ------------------ | ------------- | ------------------ | --------------------------- | --------------------------- | | Date | ❌ | DATE | java.sql.Date | DATE | java.time.LocalDate | | Date32 | ❌ | DATE | java.sql.Date | DATE | java.time.LocalDate | | DateTime | ❌ | TIMESTAMP | java.sql.Timestamp | TIMESTAMP | java.time.OffsetDateTime | | DateTime64 | ❌ | TIMESTAMP | java.sql.Timestamp | TIMESTAMP | java.time.OffsetDateTime | | Time | ✅ | TIME | java.sql.Time | новый тип/не поддерживается | новый тип/не поддерживается | | Time64 | ✅ | TIME | java.sql.Time | новый тип/не поддерживается | новый тип/не поддерживается | * `Time` и `Time64` поддерживаются в V2 только в качестве новых типов. * `DateTime` и `DateTime64` сопоставляются с `java.sql.Timestamp` для обеспечения лучшей совместимости с JDBC. **Типы enum** | Тип данных ClickHouse | Совместимость с V1 | Тип JDBC (V2) | Класс Java (V2) | Тип JDBC (V1) | Класс Java (V1) | | --------------------- | ------------------ | ------------- | ---------------- | ------------- | ---------------- | | Enum | ✅ | VARCHAR | java.lang.String | OTHER | java.lang.String | | Enum8 | ✅ | VARCHAR | java.lang.String | OTHER | java.lang.String | | Enum16 | ✅ | VARCHAR | java.lang.String | OTHER | java.lang.String | **Вложенные типы** | Тип ClickHouse | Совместимость с V1 | Тип JDBC (V2) | Класс Java (V2) | Тип JDBC (V1) | Класс Java (V1) | | -------------- | ------------------ | ------------- | --------------- | ------------- | -------------------------------------- | | Массив | ❌ | ARRAY | 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