Driver JDBC

​

Prérequis environnementaux

• OpenJDK version >= 8

​

Configuration

{/* 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 et ajoutez-le au classpath
  • à partir de la version 0.9.4, un artefact est disponible : https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all
  • utilisez le classificateur all pour obtenir le JAR avec toutes les dépendances embarquées.
• ou depuis le dépôt officiel ici

​

Configuration

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

• un seul endpoint est autorisé dans l’URL
• le protocole doit être spécifié lorsqu’il ne s’agit pas du protocole par défaut - ‘HTTP’
• le port doit être spécifié lorsqu’il ne s’agit pas du port par défaut ‘8123’
• le driver ne déduit pas le protocole à partir du port, vous devez le spécifier explicitement
• le paramètre ssl n’est pas requis lorsque le protocole est spécifié.

​

Propriétés de connexion

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.

​

Identification du client

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

​

Identification des opérations

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

​

Types de données pris en charge

​

Correspondance de types JDBC

• ResultSet#getObject(columnIndex) - la méthode retourne un objet de la classe Java correspondante. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short, etc.)
• ResultSetMetaData#getColumnType(columnIndex) - la méthode retourne le type JDBC correspondant. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short, etc.)

• ResultSet#getObject(columnIndex, class) - la méthode essaiera de convertir la valeur en type class. Certaines conversions présentent des limitations. Voir chaque section pour plus de détails.

• les types numériques sont convertibles entre eux. Ainsi, Int8 peut être lu comme Float64, et inversement.:
  • rs.getObject(1, Float64.class) renverra une valeur Float64 pour la colonne Int8.
  • rs.getLong(1) renverra une valeur Long pour la colonne Int8.
  • rs.getByte(1) peut renvoyer une valeur Byte pour la colonne Int16 si celle-ci tient dans Byte.
• la conversion d’un type plus large vers un type plus étroit n’est pas recommandée en raison du risque de corruption des données.
• Le type Bool se comporte aussi comme un nombre.
• Tous les types numériques peuvent également être lus comme java.lang.String.
• Le stockage de Float.MAX_VALUE de Java en tant que Float pose problème (https://github.com/ClickHouse/clickhouse-java/issues/809). Enregistrer la même valeur en tant que Double résout le problème.

• String ne peut être lu que sous la forme de java.lang.String ou de byte[].
• FixedString est lu tel quel et sera complété par des zéros jusqu’à atteindre la longueur de la colonne. (Par exemple, FixedString(10) pour 'John' sera lu comme 'John\0\0\0\0\0\0\0\0\0'.)

• Enum8 et Enum16 sont associés à java.lang.String par défaut.
• Les valeurs d’énumération peuvent être lécues comme valeurs numériques à l’aide de la méthode d’accès dédiée ou de la méthode getObject(columnIndex, Integer.class).
• Enum16 est associé en interne à short et Enum8 à byte. Il faut éviter de lire Enum16 comme un byte en raison du risque de corruption des données.
• Les valeurs d’énumération peuvent être définies comme chaîne de caractères ou comme valeur numérique dans PreparedStatement.

• Les types Date / Time sont associés aux types java.sql pour une meilleure compatibilité avec JDBC. Cependant, il est possible d’obtenir des objets java.time.LocalDate, java.time.LocalDateTime ou java.time.LocalTime en utilisant ResultSet#getObject(columnIndex, Class<T>) avec la classe correspondante comme deuxième argument.
  • rs.getObject(1, java.time.LocalDate.class) renvoie la valeur java.time.LocalDate de la colonne Date.
  • rs.getObject(1, java.time.LocalDateTime.class) renvoie la valeur java.time.LocalDateTime de la colonne DateTime.
  • rs.getObject(1, java.time.LocalTime.class) renvoie la valeur java.time.LocalTime de la colonne Time.
• Date, Date32, Time, Time64 ne sont pas affectés par le fuseau horaire du serveur.
• DateTime, DateTime64 sont affectés par le fuseau horaire du serveur ou le fuseau horaire de la session.
• DateTime et DateTime64 peuvent être récupérés sous forme de ZonedDateTime à l’aide de getObject(colIndex, ZonedDateTime.class).

• Array est mappé à java.sql.Array par défaut afin d’être compatible avec JDBC. Cela permet également de fournir plus d’informations sur la valeur de tableau renvoyée. Utile pour l’inférence de type.
• Array implémente la méthode getResultSet() pour renvoyer un java.sql.ResultSet contenant les mêmes données que le tableau d’origine.
• Les types de collection ne doivent pas être lus comme des java.lang.String, car ce n’est pas une manière valide de représenter les données (par ex., les valeurs de chaîne ne sont pas entre guillemets dans un tableau).
• Map est associé à OTHER, car la valeur ne peut être lue qu’avec la méthode getObject(columnIndex, Class<T>).
  • Map n’est pas un java.sql.Struct, car il ne comporte pas de colonnes nommées.
• Tuple est associé à Object[], car il peut contenir différents types et qu’utiliser List n’est pas possible.
• Tuple peut être lu comme un Array à l’aide de la méthode getObject(columnIndex, Array.class). Dans ce cas, Array#baseTypeName renverra la définition de la colonne Tuple.

• Les types enveloppes (Nullable, LowCardinality) sont préservés dans getBaseTypeName(), mais getBaseType() correspond au code JDBC du type interne.
• Les tableaux imbriqués sont aplatis dans les métadonnées : getBaseTypeName() renvoie le type de l’élément le plus interne qui n’est pas un tableau, et non l’élément enfant immédiat.
• Les types paramétrés (FixedString(N), définitions complètes de Enum/Tuple) conservent leurs paramètres dans getBaseTypeName().

• Dans V2, getBaseTypeName() conserve la signature de type complète, y compris les types wrapper (Nullable, LowCardinality) et les paramètres de type (FixedString(8), définitions complètes de Enum et Tuple). V1 les supprime et renvoie uniquement le nom du type de base.
• Les tableaux Tuple utilisent OTHER (1111) dans V2 au lieu de STRUCT (2002), car les tuples ClickHouse ont des champs nommés, ce que java.sql.Struct ne prend pas en charge.
• Les tableaux UUID utilisent OTHER (1111) dans V2, comme pour le mappage du UUID scalaire.
• Les valeurs Enum sont mappées vers VARCHAR — les membres d’enum sont identifiés par leur nom sous forme de chaîne, indépendamment de leur encodage numérique sous-jacent.

• typeName - nom du type des éléments du tableau. Par exemple Array(Int32) -> "Int32".
• elements - éléments effectifs du tableau. Par exemple [[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 - nom du type des éléments imbriqués. Par exemple Nested(Tuple(Int32, String)) -> "Nested(Tuple(Int32, String))".
• elements - éléments imbriqués proprement dits. Par exemple [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 et LowCardinality sont des types spéciaux qui encapsulent d’autres types.
• Nullable influe sur la manière dont les noms de type sont renvoyés dans ResultSetMetaData

• UUID n’est pas un type JDBC standard. Il fait toutefois partie du JDK. Par défaut, la méthode getObject() renvoie un java.util.UUID.
• UUID peut être lu/écrit sous forme de String à l’aide de la méthode getObject(columnIndex, String.class).
• IPv4 et IPv6 ne sont pas des types JDBC standard. Ils font toutefois partie du JDK. Par défaut, la méthode getObject() renvoie un java.net.Inet4Address et un java.net.Inet6Address.
• IPv4 et IPv6 peuvent être lus/écrits sous forme de String à l’aide de la méthode 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");

​

Gestion des dates, des heures et des fuseaux horaires

​

Création d’une connexion

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

​

Fournir les identifiants et les paramètres

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
}

​

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

​

Pour aller plus loin

​

Résolution des problèmes

​

Journalisation

​

Résolution du timeout JDBC sur les insertions volumineuses

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. Ajustez les paramètres suivants du noyau Linux dans /etc/sysctl.conf ou dans un fichier de configuration connexe :

• 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 (Vous pouvez envisager d’abaisser cette valeur par rapport à la valeur default de 300 secondes)

2. Après avoir modifié les paramètres du noyau, appliquez les modifications en exécutant la commande suivante :

sudo sysctl -p

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

​

Guide de migration

​

Modifications principales

• JDBC V2 a été conçu pour être plus léger, et certaines fonctionnalités ont été supprimées.
  • JDBC V2 ne prend pas en charge les données en streaming, car elles ne font partie ni de la spécification JDBC ni de Java.
• JDBC V2 nécessite une configuration explicite. Aucun basculement n’est défini par défaut.
  • Le protocole doit être indiqué dans l’URL. Aucune détection implicite du protocole en fonction du numéro de port.

​

Modifications de configuration

• com.clickhouse.jdbc.DriverProperties - les propriétés de configuration propres au driver.
• com.clickhouse.client.api.ClientConfigProperties - les propriétés de configuration du client. Les changements de configuration du client sont décrits dans la documentation du client Java.

• L’URL est d’abord analysée pour les propriétés. Celles-ci remplacent toutes les autres propriétés.
• Les propriétés du driver ne sont pas transmises au client.
• Les endpoints (hôte, port, protocole) sont extraits de l’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
}

​

Modifications des types de données

• La principale différence est que les types non signés sont associés à des types Java pour une meilleure portabilité.

• FixedString est lu tel quel dans les deux versions. Par exemple, FixedString(10) pour 'John' sera lu sous la forme 'John\0\0\0\0\0\0\0\0\0'.
• Lorsque PreparedStatement#setBytes est utilisé, il est converti en unhex('<hex_string>'), puis lu en tant que String.
• Les chaînes sont stockées en encodage UTF-8.

• Time et Time64 sont pris en charge dans V2 uniquement en tant que nouveaux types.
• DateTime et DateTime64 sont associés à java.sql.Timestamp pour une meilleure compatibilité avec JDBC.

• En V2, Array est associé à java.sql.Array par défaut pour assurer la compatibilité avec JDBC. Cela permet aussi de fournir davantage d’informations sur la valeur de tableau renvoyée. Utile pour l’inférence de type.
• En V2, Array implémente la méthode getResultSet() afin de renvoyer un java.sql.ResultSet avec le même contenu que le tableau d’origine.
• V1 utilise STRUCT pour Map, mais renvoie toujours un objet java.util.Map. V2 corrige cela en associant Map à JAVA_OBJECT.
• V1 utilise STRUCT pour Tuple, mais renvoie toujours un objet List<Object>. V2 associe Tuple à OTHER et renvoie Object[] par défaut.
• V2 introduit com.clickhouse.data.Tuple#Tuple pour écrire des tuples. Cela permet de déterminer plus facilement si une valeur est un tuple ou un tableau.
• PreparedStatement#setBytes et ResultSet#getBytes ne peuvent pas être utilisés avec des types de collection. Ces méthodes sont conçues pour fonctionner avec des chaînes binaires.
• En général, java.sql.Array est utilisé pour écrire et lire les types Array. Le pilote JDBC le prend entièrement en charge.
• En V2, Nested est associé à Array et est présenté comme un tableau de tuples.
• V2 prend partiellement en charge java.sql.Struct, car il est très similaire au type Array et ne prend pas en charge les paires clé-valeur. Struct peut être utilisé pour écrire des valeurs Tuple.

• Nullable et LowCardinality sont des types spéciaux qui encapsulent d’autres types.
• Aucun changement n’est apporté à ces types dans V2.

• V1 utilise VARCHAR pour UUID, mais renvoie toujours un objet java.util.UUID. V2 corrige cela en associant UUID à OTHER et renvoie un objet java.util.UUID.
• V1 utilise VARCHAR pour IPv4 et IPv6, mais renvoie toujours des objets java.net.Inet4Address et java.net.Inet6Address. V2 corrige cela en associant IPv4 et IPv6 à OTHER et renvoie des objets java.net.Inet4Address et java.net.Inet6Address.
• Dynamic et Variant sont de nouveaux types dans V2. Ils ne sont pas pris en charge dans V1.
• JSON est basé sur le type Dynamic. Il n’est donc pris en charge que dans V2.
• Les valeurs IPv4 et IPv6 peuvent être lues sous forme de byte[] à l’aide de la méthode getBytes(columnIndex). Il est toutefois recommandé d’utiliser les classes prévues pour ces types.
• V2 ne prend pas en charge la lecture d’une adresse IP sous forme de valeurs numériques, car la conversion est mieux gérée dans les classes InetAddress.

​

Modifications des métadonnées de la base de données

• V2 utilise uniquement le terme Schema pour désigner les bases de données. Le terme Catalog est réservé à un usage futur.
• V2 renvoie false pour DatabaseMetaData.supportsTransactions() et DatabaseMetaData.supportsSavepoints(). Cela sera modifié dans une future version.
• Dans DatabaseMetaData.getTypeInfo(), les colonnes LITERAL_PREFIX et LITERAL_SUFFIX renvoient désormais null pour les types de données auxquels des préfixes et suffixes ne s’appliquent pas (par ex., les types numériques). Dans V1, ces colonnes renvoyaient des valeurs non nulles pour ces types. Ces colonnes doivent être utilisées lors de la génération de requêtes SQL afin de mettre correctement entre guillemets les valeurs littérales en fonction de leur type de données.