Java clients overview

• Client 0.8+
• JDBC 0.8+
• R2DBC Driver

ClickHouse client

Java client is a library implementing own API that abstracts details of network communications with ClickHouse server. Currently HTTP Interface is supported only. The library provide utilities to work with different ClickHouse formats and other related functions.

Java Client was developed far back in 2015. Its codebase became very hard to maintain, API is confusing, it is hard to optimize it further. So we have refactored it in 2024 into a new component client-v2. It has clear API, lighter codebase and more performance improvements, better ClickHouse formats support (RowBinary & Native mainly). JDBC will use this client in near feature.

Supported data types

Data Type	Client V2 Support	Client V1 Support
Int8	✔	✔
Int16	✔	✔
Int32	✔	✔
Int64	✔	✔
Int128	✔	✔
Int256	✔	✔
UInt8	✔	✔
UInt16	✔	✔
UInt32	✔	✔
UInt64	✔	✔
UInt128	✔	✔
UInt256	✔	✔
Float32	✔	✔
Float64	✔	✔
Decimal	✔	✔
Decimal32	✔	✔
Decimal64	✔	✔
Decimal128	✔	✔
Decimal256	✔	✔
Bool	✔	✔
String	✔	✔
FixedString	✔	✔
Nullable	✔	✔
Date	✔	✔
Date32	✔	✔
DateTime	✔	✔
DateTime32	✔	✔
DateTime64	✔	✔
Interval	✗	✗
Enum	✔	✔
Enum8	✔	✔
Enum16	✔	✔
Array	✔	✔
Map	✔	✔
Nested	✔	✔
Tuple	✔	✔
UUID	✔	✔
IPv4	✔	✔
IPv6	✔	✔
Object	✗	✔
Point	✔	✔
Nothing	✔	✔
MultiPolygon	✔	✔
Ring	✔	✔
Polygon	✔	✔
SimpleAggregateFunction	✔	✔
AggregateFunction*	✔	✔
Variant	✔	✗
Dynamic	✔	✗
JSON	✔	✗

ClickHouse Data Types

Partial support

• AggregateFunction — Only groupBitmap is supported for direct binary reads. For other aggregate functions (min, max, avg, etc.), use -Merge combinators in your query (e.g., minMerge(), avgMerge()) to resolve the state server-side. SELECT * FROM table ... is not supported for columns with AggregateFunction type.

Data type notes

• Decimal — SET output_format_decimal_trailing_zeros=1 in 21.9+ for consistency.
• Enum — can be treated as both string and integer.
• UInt64 — mapped to long in client-v1.

Features

Table of features of the clients:

Name	Client V2	Client V1	Comments
Http Connection	✔	✔
Http Compression (LZ4)	✔	✔
Application Controlled Compression	✔	✗
Server Response Compression - LZ4	✔	✔
Client Request Compression - LZ4	✔	✔
HTTPS	✔	✔
Client SSL Cert (mTLS)	✔	✔
Http Proxy	✔	✔
POJO SerDe	✔	✗
Connection Pool	✔	✔	When Apache HTTP Client used
Named Parameters	✔	✔
Retry on failure	✔	✔
Failover	✗	✔
Load-balancing	✗	✔
Server auto-discovery	✗	✔
Log Comment	✔	✔
Session Roles	✔	✔
SSL Client Authentication	✔	✔
SNI Configuration	✔	✗
Session timezone	✔	✔

JDBC Drive inherits same features as underlying client implementation. Other JDBC features are listed on its page.

Compatibility

• All projects in this repo are tested with all active LTS versions of ClickHouse.
• Support policy
• We recommend to upgrade client continuously to not miss security fixes and new improvements
• If you have an issue with migration to v2 API - create an issue and we will respond!

Logging

Our Java language client uses SLF4J for logging. You can use any SLF4J-compatible logging framework, such as Logback or Log4j. For example, if you're using Maven you could add the following dependency to your pom.xml file:

<dependencies>
    <!-- SLF4J API -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.16</version> <!-- Use the latest version -->
    </dependency>

    <!-- Logback Core -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-core</artifactId>
        <version>1.5.16</version> <!-- Use the latest version -->
    </dependency>

    <!-- Logback Classic (bridges SLF4J to Logback) -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.16</version> <!-- Use the latest version -->
    </dependency>
</dependencies>

Configuring logging

This is going to depend on the logging framework you're using. For example, if you're using Logback, you could configure logging in a file called logback.xml:

<configuration>
    <!-- Console Appender -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>[%d{yyyy-MM-dd HH:mm:ss}] [%level] [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- File Appender -->
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>logs/app.log</file>
        <append>true</append>
        <encoder>
            <pattern>[%d{yyyy-MM-dd HH:mm:ss}] [%level] [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Root Logger -->
    <root level="info">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>

    <!-- Custom Log Levels for Specific Packages -->
    <logger name="com.clickhouse" level="info" />
</configuration>

Changelog