JDBC driver

​

Environment requirements

• OpenJDK version >= 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 and add it to the classpath
  • starting from version 0.9.4 there is an artifact https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all
  • use qualifier all to get the jar with all shaded dependencies included.
• or from official repository here

​

Configuration

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

• only one endpoint is allowed in the URL
• protocol should be specified when it isn’t the default one - ‘HTTP’
• port should be specified when it isn’t the default one ‘8123’
• driver don’t guess the protocol from the port, you need to specify it explicitly
• ssl parameter isn’t required when protocol is specified.

​

Connection Properties

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.

​

Client Identification

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

​

Operation Identification

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

​

Supported data types

​

JDBC Type Mapping

• ResultSet#getObject(columnIndex) - method will return object of the corresponding Java class. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short, etc.)
• ResultSetMetaData#getColumnType(columnIndex) - method will return the corresponding JDBC type. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short, etc.)

• ResultSet#getObject(columnIndex, class) - method will try to convert value to class type. There are some conversion limitations. See each section for details.

• numeric types are interconvertible. So Int8 can be get as Float64 and vice versa.:
  • rs.getObject(1, Float64.class) will return Float64 value of Int8 column.
  • rs.getLong(1) will return Long value of Int8 column.
  • rs.getByte(1) can return Byte value of Int16 column if it fits into Byte.
• conversion from wider to narrower type isn’t recommend because of data coruption risk.
• Bool type acts as number, too.
• All number types can be read as java.lang.String.
• Storing java Float.MAX_VALUE as Float has issue (https://github.com/ClickHouse/clickhouse-java/issues/809). Saving same value as Double solves the issue.

• String can be read only as java.lang.String or byte[].
• FixedString is read as is and will be padded with zeros to the length of the column. (For example FixedString(10) for 'John' will be read as 'John\0\0\0\0\0\0\0\0\0'.)

• Enum8 and Enum16 are mapped to java.lang.String by default.
• Enum values can be read as numeric values using designtated getter method or getObject(columnIndex, Integer.class) method.
• Enum16 is mapped to short and Enum8 is mapped to byte internally. Reading Enum16 as byte should be avoided because of data coruption risk.
• Enum values can be set as string or numeric value in PreparedStatement.

• Date / Time types are mapped to java.sql types for better compatibility with JDBC. However getting java.time.LocalDate, java.time.LocalDateTime, java.time.LocalTime is possible by using ResultSet#getObject(columnIndex, Class<T>) with the corresponding class as the second argument.
  • rs.getObject(1, java.time.LocalDate.class) will return java.time.LocalDate value of Date column.
  • rs.getObject(1, java.time.LocalDateTime.class) will return java.time.LocalDateTime value of DateTime column.
  • rs.getObject(1, java.time.LocalTime.class) will return java.time.LocalTime value of Time column.
• Date, Date32, Time, Time64 isn’t affected by the timezone of the server.
• DateTime, DateTime64 is affected by the timezone of the server or session timezone.
• DateTime and DateTime64 can be retrieved as ZonedDateTime by using getObject(colIndex, ZonedDateTime.class).

• Array is mapped to java.sql.Array by default to be compatible with JDBC. This is also done to give more information about returned array value. Useful for type inference.
• Array implements getResultSet() method to return java.sql.ResultSet with the same content as the original array.
• Collection types shouldn’t be read as java.lang.String because it isn’t a valid way to represent the data (Ex. there is no quoting for string values in array).
• Map is mapped to OTHER because value can be read only with getObject(columnIndex, Class<T>) method.
  • Map isn’t a java.sql.Struct because it doesn’t have named columns.
• Tuple is mapped to Object[] because it can contain different types and using List isn’t valid.
• Tuple can be read as Array by using getObject(columnIndex, Array.class) method. In this case Array#baseTypeName will return Tuple column definition.

• Wrapper types (Nullable, LowCardinality) are preserved in getBaseTypeName() but getBaseType() resolves to the inner type’s JDBC code.
• Nested arrays are flattened in the metadata: getBaseTypeName() returns the innermost non-array element type, not the immediate child.
• Parameterized types (FixedString(N), full Enum/Tuple definitions) keep their parameters in getBaseTypeName().

• In V2, getBaseTypeName() preserves the full type signature including wrapper types (Nullable, LowCardinality) and type parameters (FixedString(8), full Enum and Tuple definitions). V1 strips these and returns only the base type name.
• Tuple arrays use OTHER (1111) in V2 instead of STRUCT (2002) because ClickHouse tuples have named fields, which java.sql.Struct does not support.
• UUID arrays use OTHER (1111) in V2, matching the scalar UUID mapping.
• Enum values map to VARCHAR — enum members are identified by string name regardless of their underlying numeric encoding.

• typeName - type name of the array elements. For example Array(Int32) -> "Int32".
• elements - actual array elements. For example [[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 - type name of the nested elements. For example Nested(Tuple(Int32, String)) -> "Nested(Tuple(Int32, String))".
• elements - actual nested elements. For example [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 and LowCardinality are special types that wrap other types.
• Nullable affects how type names are returned in ResultSetMetaData

• UUID isn’t JDBC standard type. However it is part of JDK. By default java.util.UUID is returned on getObject() method.
• UUID can be read/written as String by using getObject(columnIndex, String.class) method.
• IPv4 and IPv6 aren’t JDBC standard types. However they’re part of JDK. By default java.net.Inet4Address and java.net.Inet6Address are returned on getObject() method.
• IPv4 and IPv6 can be read/written as String by using getObject(columnIndex, String.class) method.

{
    "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");

​

Handling Dates, Times, and Timezones

​

Creating Connection

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

​

Supplying Credentials and Settings

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
}

​

Simple Statement

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

​

More Information

​

Troubleshooting

​

Logging

​

Resolving JDBC Timeout on Large Inserts

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. Adjust the following Linux kernel parameters in /etc/sysctl.conf or a related configuration file:

• 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 (You may consider lowering this value from the default 300 seconds)

2. After modifying the kernel parameters, apply the changes by running the following command:

sudo sysctl -p

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

​

Migration Guide

​

Key Changes

• JDBC V2 is implemented to be more lightweight and some features were removed.
  • Streaming Data isn’t supported in JDBC V2 because it isn’t part of the JDBC spec and Java.
• JDBC V2 expects explicit configuration. No failover defaults.
  • Protocol should be specified in the URL. No implicit protocol detection using port numbers.

​

Configuration Changes

• com.clickhouse.jdbc.DriverProperties - the driver own configuration properties.
• com.clickhouse.client.api.ClientConfigProperties - the client configuration properties. Client configuration changes are described in the Java Client documentation.

• URL is parsed first for properties. They override all other properties.
• Driver properties aren’t passed to the client.
• Endpoints (host, port, protocol) are parsed from the 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
}

​

Data Types Changes

• The biggest differences is that unsigned types are mapped to java types for better portability.

• FixedString is read as is in both versions. For example FixedString(10) for 'John' will be read as 'John\0\0\0\0\0\0\0\0\0'.
• When PreparedStatement#setBytes is used it will be converted to unhex('<hex_string>') and then read as String.
• Strings are stored in UTF-8 encoding.

• Time and Time64 are supported in V2 only as new types.
• DateTime and DateTime64 are mapped to java.sql.Timestamp for better compatibility with JDBC.

• In V2 Array is mapped to java.sql.Array by default to be compatible with JDBC. This is also done to give more information about returned array value. Useful for type inference.
• In V2 Array implements getResultSet() method to return java.sql.ResultSet with the same content as the original array.
• V1 uses STRUCT for Map but returns java.util.Map object always. V2 fixes this by mapping Map to JAVA_OBJECT.
• V1 uses STRUCT for Tuple but returns List<Object> object always. V2 maps Tuple to OTHER and returns Object[] by default.
• V2 introduces com.clickhouse.data.Tuple#Tuple to write tuples. It simplifies determining if value is a tuple or and array.
• PreparedStatement#setBytes and ResultSet#getBytes cannot be used with collection types. These methods are designed to work with binary strings.
• Normally java.sql.Array is used to write and read Array types. JDBC driver has full support for this.
• V2 Nested is mapped to Array and presents it as array of tuples.
• V2 has partial support for java.sql.Struct because it very similar to Array type and doesn’t support key-value pairs. Struct can be used to write Tuple values.

• Nullable and LowCardinality are special types that wrap other types.
• No changes are made to these types in V2.

• V1 uses VARCHAR for UUID but returns java.util.UUID object always. V2 fixes this by mapping UUID to OTHER and returns java.util.UUID object.
• V1 uses VARCHAR for IPv4 and IPv6 but returns java.net.Inet4Address and java.net.Inet6Address objects always. V2 fixes this by mapping IPv4 and IPv6 to OTHER and returns java.net.Inet4Address and java.net.Inet6Address objects.
• Dynamic and Variant are new types in V2. Not supported in V1.
• JSON is based on Dynamic type. Therefore it is supported only in V2.
• IPv4 and IPv6 values can be read as byte[] by using getBytes(columnIndex) method. However it is recommended to use designated classes for these types.
• V2 do not support reading IP address as numeric values because convertion is better implementation in InetAddress classes.

​

Database Metadata Changes

• V2 uses only Schema term to name databases. Catalog term is reserved for future use.
• V2 returns false for DatabaseMetaData.supportsTransactions() and DatabaseMetaData.supportsSavepoints(). This will be changed in the future development.
• In DatabaseMetaData.getTypeInfo(), the LITERAL_PREFIX and LITERAL_SUFFIX columns now return null for data types where prefixes and suffixes are not expected (e.g., numeric types). In V1, these columns returned non-null values for such types. These columns should be used when generating SQL queries to properly quote literal values according to their data type.