JDBC-драйвер

​

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

• OpenJDK версии >= 8

​

Setup

{/* https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc */}
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.9.8</version>
    <classifier>all</classifier>
</dependency>

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

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

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

​

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

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

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

​

Свойства подключения

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

​

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

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

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

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

​

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

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

​

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

​

Соответствие типов 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. Существуют некоторые ограничения на преобразование. Подробнее см. в соответствующих разделах.

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

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

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

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

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

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

• В V2 getBaseTypeName() сохраняет полную сигнатуру типа, включая типы-обёртки (Nullable, LowCardinality) и параметры типа (FixedString(8), полные определения Enum и Tuple). V1 убирает их и возвращает только имя базового типа.
• Массивы Tuple в V2 используют OTHER (1111) вместо STRUCT (2002), потому что кортежи ClickHouse имеют именованные поля, а java.sql.Struct их не поддерживает.
• Массивы UUID в V2 используют OTHER (1111), что соответствует сопоставлению скалярного UUID.
• Значения Enum сопоставляются с VARCHAR — элементы enum идентифицируются по строковому имени независимо от базовой числовой кодировки.

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

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();
    }
}

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

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();
    }
}

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());
        }
    }
}

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();
    }
}

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

• 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();
    }
}

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

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

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

{
    "key1": "value1",
    "key2": ["value2", "value3"]
    "key3": {
        "key4": "value4",
        "key5": "value5"
    }
}

Map<String, Object> map = new HashMap<>();
map.put("key1", "value1");
map.put("key2", Arrays.asList("value2", "value3"));
map.put("key3", new HashMap<String, Object>() {{
    put("key4", "value4");
    put("key5", "value5");
}});

Properties properties = new Properties();
properties.setProperty(
                ClientConfigProperties.serverSetting(ServerSettings.OUTPUT_FORMAT_BINARY_WRITE_JSON_AS_STRING),
                "1");
try (Connection conn = DriverManager.getConnection(url, properties)) {
     try (ResultSet rs = stmt.executeQuery("SELECT * FROM test_json ORDER BY order")) {
        while (rs.next()) {
            String json = rs.getString("json");
            // ...
        }
    }
}

Properties properties = new Properties();
properties.put(ClientConfigProperties.serverSetting("output_format_json_quote_64bit_integers"), "0");
properties.put(ClientConfigProperties.serverSetting("output_format_json_quote_64bit_floats"), "0");
properties.put(ClientConfigProperties.serverSetting("output_format_json_quote_decimals"), "0");

​

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

​

Создание подключения

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

​

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

​

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

​

Логирование

​

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

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

​

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

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

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

​

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

​

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

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

​

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

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

• Сначала URL разбирается на свойства. Они имеют приоритет над всеми остальными свойствами.
• Свойства драйвера не передаются клиенту.
• Параметры конечной точки (хост, порт, протокол) разбираются из 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
}

​

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

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

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

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

• В 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 нельзя использовать с типами коллекций. Эти методы предназначены для работы с двоичными данными.
• Обычно java.sql.Array используется для записи и чтения значений типа Array. Драйвер JDBC полностью это поддерживает.
• В V2 Nested сопоставляется с Array и представляется как массив кортежей.
• V2 частично поддерживает java.sql.Struct, поскольку этот тип очень похож на Array и не поддерживает пары «ключ-значение». Struct можно использовать для записи значений Tuple.

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

• 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(). В дальнейшем это будет изменено.
• В DatabaseMetaData.getTypeInfo() столбцы LITERAL_PREFIX и LITERAL_SUFFIX теперь возвращают null для типов данных, для которых префиксы и суффиксы не используются (например, для числовых типов). В V1 эти столбцы возвращали ненулевые значения для таких типов. Эти столбцы следует использовать при генерации SQL-запросов, чтобы корректно заключать литеральные значения в кавычки в соответствии с их типом данных.