> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Java clients overview

> Options for connecting to ClickHouse from Java

* [Client 0.8+](/integrations/language-clients/java/client)
* [JDBC 0.8+](/integrations/language-clients/java/jdbc)
* [R2DBC Driver](/integrations/language-clients/java/r2dbc)

<h2 id="clickhouse-client">
  ClickHouse client
</h2>

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.

<h3 id="supported-data-types">
  Supported data types
</h3>

| **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](/reference/data-types/index)

<Info>
  **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.
</Info>

<Info>
  **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.
</Info>

<h3 id="features">
  Features
</h3>

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](/integrations/language-clients/java/jdbc).

<h3 id="compatibility">
  Compatibility
</h3>

* All projects in this repo are tested with all [active LTS versions](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) of ClickHouse.
* [Support policy](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md#security-change-log-and-support)
* 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](https://github.com/ClickHouse/clickhouse-java/issues/new?assignees=\&labels=v2-feedback\&projects=\&template=v2-feedback.md\&title=) and we will respond!

<h3 id="logging">
  Logging
</h3>

Our Java language client uses [SLF4J](https://www.slf4j.org/) 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:

```xml title="pom.xml" theme={null}
<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>
```

<h4 id="configuring-logging">
  Configuring logging
</h4>

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

```xml title="logback.xml" theme={null}
<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](https://github.com/ClickHouse/clickhouse-java/blob/main/CHANGELOG.md)