Driver JDBC

​

Requisitos del entorno

• OpenJDK versión >= 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 y agrégalo al classpath
  • a partir de la versión 0.9.4, está disponible el artefacto https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all
  • use el calificador all para obtener el JAR con todas las dependencias empaquetadas incluidas.
• o desde el repositorio oficial aquí

​

Configuración

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

• solo se permite un único endpoint en la URL
• se debe especificar el protocolo cuando no sea el predeterminado - ‘HTTP’
• se debe especificar el puerto cuando no sea el predeterminado ‘8123’
• el driver no infiere el protocolo a partir del puerto, debe especificarlo explícitamente
• El parámetro ssl no se requiere cuando se especifica el protocolo.

​

Propiedades de conexión

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.

​

Identificación del cliente

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

​

Identificación de operaciones

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

​

Tipos de datos compatibles

​

Correspondencia de tipos JDBC

• ResultSet#getObject(columnIndex) - el método devuelve un objeto de la clase Java correspondiente. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short, etc.)
• ResultSetMetaData#getColumnType(columnIndex) - el método devuelve el tipo JDBC correspondiente. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short, etc.)

• ResultSet#getObject(columnIndex, class) - el método intentará convertir el valor al tipo class. Hay algunas limitaciones de conversión. Consulta cada sección para ver más detalles.

• los tipos numéricos son convertibles entre sí. Así, Int8 se puede obtener como Float64 y viceversa.:
  • rs.getObject(1, Float64.class) devolverá un valor Float64 de la columna Int8.
  • rs.getLong(1) devolverá un valor Long de la columna Int8.
  • rs.getByte(1) puede devolver un valor Byte de la columna Int16 si cabe en Byte.
• no se recomienda la conversión de un tipo de mayor capacidad a uno de menor capacidad debido al riesgo de corrupción de datos.
• El tipo Bool también funciona como número.
• Todos los tipos numéricos pueden leerse como java.lang.String.
• Almacenar Float.MAX_VALUE de Java como Float presenta un problema (https://github.com/ClickHouse/clickhouse-java/issues/809). Guardar ese mismo valor como Double lo resuelve.

• String solo se puede leer como java.lang.String o byte[].
• FixedString se lee tal cual y se rellena con ceros hasta alcanzar la longitud de la columna. (Por ejemplo, FixedString(10) para 'John' se leerá como 'John\0\0\0\0\0\0\0\0\0'.)

• Enum8 y Enum16 se asignan a java.lang.String de manera predeterminada.
• Los valores enum pueden leerse como valores numéricos mediante el método getter correspondiente o el método getObject(columnIndex, Integer.class).
• Enum16 se mapea internamente a short y Enum8 se mapea a byte. Debe evitarse leer Enum16 como byte debido al riesgo de corrupción de datos.
• Los valores de enum pueden establecerse como una cadena o un valor numérico en PreparedStatement.

• Los tipos Date / Time se asignan a tipos java.sql para lograr una mejor compatibilidad con JDBC. Sin embargo, es posible obtener java.time.LocalDate, java.time.LocalDateTime y java.time.LocalTime mediante ResultSet#getObject(columnIndex, Class<T>), usando la clase correspondiente como segundo argumento.
  • rs.getObject(1, java.time.LocalDate.class) devolverá un valor java.time.LocalDate de la columna Date.
  • rs.getObject(1, java.time.LocalDateTime.class) devolverá un valor java.time.LocalDateTime de la columna DateTime.
  • rs.getObject(1, java.time.LocalTime.class) devolverá un valor java.time.LocalTime de la columna Time.
• Date, Date32, Time, Time64 no se ven afectados por la zona horaria del servidor.
• DateTime y DateTime64 se ven afectados por la zona horaria del servidor o de la sesión.
• DateTime y DateTime64 se pueden recuperar como ZonedDateTime mediante getObject(colIndex, ZonedDateTime.class).

• Array se asigna a java.sql.Array de forma predeterminada para mantener la compatibilidad con JDBC. Esto también se hace para proporcionar más información sobre el valor de array devuelto. Resulta útil para la inferencia de tipos.
• Array implementa el método getResultSet() para devolver un java.sql.ResultSet con el mismo contenido que el array original.
• Los tipos de colección no deberían interpretarse como java.lang.String, ya que no es una forma válida de representar los datos (p. ej., en un array no se usan comillas para los valores de cadena).
• Map se asigna a OTHER porque el valor solo puede leerse mediante el método getObject(columnIndex, Class<T>).
  • Map no es un java.sql.Struct porque no tiene columnas con nombres.
• Tuple se mapea a Object[] porque puede contener distintos tipos y no es válido usar List.
• Tuple puede leerse como Array mediante el método getObject(columnIndex, Array.class). En este caso, Array#baseTypeName devolverá la definición de la columna Tuple.

• Los tipos de envoltorio (Nullable, LowCardinality) se conservan en getBaseTypeName(), pero getBaseType() se resuelve como el código JDBC del tipo interno.
• Los arrays anidados se aplanan en los metadatos: getBaseTypeName() devuelve el tipo del elemento más interno que no sea un array, no el hijo inmediato.
• Los tipos parametrizados (FixedString(N), definiciones completas de Enum/Tuple) conservan sus parámetros en getBaseTypeName().

• En V2, getBaseTypeName() conserva la firma de tipo completa, incluidos los tipos envoltorio (Nullable, LowCardinality) y los parámetros de tipo (FixedString(8), las definiciones completas de Enum y Tuple). V1 los elimina y devuelve solo el nombre del tipo base.
• Los arrays de Tuple usan OTHER (1111) en V2 en lugar de STRUCT (2002) porque las tuplas de ClickHouse tienen campos con nombre, algo que java.sql.Struct no admite.
• Los arrays de UUID usan OTHER (1111) en V2, en consonancia con la asignación escalar de UUID.
• Los valores Enum se asignan a VARCHAR: los miembros de enum se identifican por su nombre de cadena, independientemente de su codificación numérica subyacente.

• typeName - nombre del tipo de los elementos del array. Por ejemplo, Array(Int32) -> "Int32".
• elements - los elementos reales del array. Por ejemplo [[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 - nombre del tipo de los elementos anidados. Por ejemplo, Nested(Tuple(Int32, String)) -> "Nested(Tuple(Int32, String))".
• elements - los elementos anidados propiamente dichos. Por ejemplo [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 y LowCardinality son tipos especiales que envuelven otros tipos.
• Nullable afecta a la forma en que se devuelven los nombres de tipo en ResultSetMetaData

• UUID no es un tipo estándar de JDBC. Sin embargo, forma parte del JDK. De forma predeterminada, el método getObject() devuelve java.util.UUID.
• UUID puede leerse y escribirse como String mediante el método getObject(columnIndex, String.class).
• IPv4 e IPv6 no son tipos estándar de JDBC. Sin embargo, forman parte del JDK. De forma predeterminada, el método getObject() devuelve java.net.Inet4Address y java.net.Inet6Address.
• IPv4 y IPv6 se pueden leer y escribir como String mediante el método 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");

​

Manejo de fechas, horas y zonas horarias

​

Creación de conexión

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

​

Suministro de credenciales y configuración

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
}

​

Instrucción simple

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

​

Insert

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

​

Más información

​

Solución de problemas

​

Registro

​

Resolución de timeout de JDBC en inserts de gran volumen

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. Ajuste los siguientes parámetros del kernel de Linux en /etc/sysctl.conf o en un archivo de configuración relacionado:

• 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 (Puede considerar reducir este valor desde el valor predeterminado de 300 segundos)

2. Después de modificar los parámetros del kernel, aplique los cambios ejecutando el siguiente comando:

sudo sysctl -p

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

​

Guía de migración

​

Cambios principales

• JDBC V2 se ha implementado para que sea más ligero y se han eliminado algunas funcionalidades.
  • El streaming de datos no es compatible con JDBC V2 porque no forma parte de la especificación de JDBC ni de Java.
• JDBC V2 requiere una configuración explícita. No hay valores predeterminados para failover.
  • El protocolo debe especificarse en la URL. No se detecta implícitamente a partir de los números de puerto.

​

Cambios de configuración

• com.clickhouse.jdbc.DriverProperties - las propiedades de configuración del propio driver.
• com.clickhouse.client.api.ClientConfigProperties - las propiedades de configuración del cliente. Los cambios en la configuración del cliente se describen en la documentación del cliente Java.

• La URL se procesa primero para extraer las propiedades. Estas prevalecen sobre todas las demás propiedades.
• Las propiedades del driver no se pasan al cliente.
• Los endpoints (host, port, protocol) se extraen de la 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
}

​

Cambios en los tipos de datos

• La principal diferencia es que los tipos sin signo se corresponden con tipos de Java para mejorar la portabilidad.

• FixedString se lee tal cual en ambas versiones. Por ejemplo, FixedString(10) para 'John' se leerá como 'John\0\0\0\0\0\0\0\0\0'.
• Cuando se utiliza PreparedStatement#setBytes, se convierte en unhex('<hex_string>') y luego se interpreta como String.
• Las cadenas se almacenan con codificación UTF-8.

• Time y Time64 solo son compatibles en V2 como tipos nuevos.
• DateTime y DateTime64 se asignan a java.sql.Timestamp para mejorar la compatibilidad con JDBC.

• En V2, Array se asigna a java.sql.Array de forma predeterminada para ser compatible con JDBC. Esto también se hace para proporcionar más información sobre el valor de array devuelto. Útil para la inferencia de tipos.
• En V2, Array implementa el método getResultSet() para devolver un java.sql.ResultSet con el mismo contenido que el array original.
• V1 usa STRUCT para Map, pero siempre devuelve un objeto java.util.Map. V2 corrige esto al mapear Map a JAVA_OBJECT.
• V1 usa STRUCT para Tuple, pero siempre devuelve un objeto List<Object>. V2 asigna Tuple a OTHER y devuelve Object[] de forma predeterminada.
• V2 introduce com.clickhouse.data.Tuple#Tuple para escribir tuplas. Simplifica la tarea de determinar si un valor es una tupla o un Array.
• PreparedStatement#setBytes y ResultSet#getBytes no pueden usarse con tipos de colección. Estos métodos están diseñados para trabajar con cadenas binarias.
• Normalmente, java.sql.Array se utiliza para escribir y leer tipos Array. El controlador JDBC ofrece compatibilidad total con ello.
• V2 asigna Nested a Array y lo presenta como un array de tuplas.
• V2 ofrece compatibilidad parcial con java.sql.Struct porque es muy similar al tipo Array y no admite pares clave-valor. Struct puede utilizarse para escribir valores Tuple.

• Nullable y LowCardinality son tipos especiales que encapsulan otros tipos.
• No se realizan cambios en estos tipos en la V2.

• V1 usa VARCHAR para UUID, pero siempre devuelve un objeto java.util.UUID. V2 corrige esto al mapear UUID a OTHER y devuelve un objeto java.util.UUID.
• V1 usa VARCHAR para IPv4 e IPv6, pero siempre devuelve objetos java.net.Inet4Address y java.net.Inet6Address. V2 corrige esto asignando IPv4 e IPv6 a OTHER y devuelve objetos java.net.Inet4Address y java.net.Inet6Address.
• Dynamic y Variant son tipos nuevos en V2. No se admiten en V1.
• JSON se basa en el tipo Dynamic. Por ello, solo se admite en V2.
• Los valores IPv4 e IPv6 pueden leerse como byte[] mediante el método getBytes(columnIndex). Sin embargo, se recomienda usar las clases específicas para estos tipos.
• V2 no admite la lectura de direcciones IP como valores numéricos porque la conversión está mejor implementada en las clases InetAddress.

​

Cambios en los metadatos de la base de datos

• V2 usa únicamente el término Schema para referirse a las bases de datos. El término Catalog queda reservado para usos futuros.
• V2 devuelve false para DatabaseMetaData.supportsTransactions() y DatabaseMetaData.supportsSavepoints(). Esto cambiará en el futuro.
• En DatabaseMetaData.getTypeInfo(), las columnas LITERAL_PREFIX y LITERAL_SUFFIX ahora devuelven null para los tipos de datos en los que no se esperan prefijos ni sufijos (por ejemplo, los tipos numéricos). En V1, estas columnas devolvían valores no nulos para esos tipos. Estas columnas deben usarse al generar consultas SQL para entrecomillar correctamente los valores literales según su tipo de dato.