clickhouse-java: two clients, two JDBC drivers and an unfinished migration

Why two of everything

The repository publishes the same idea twice. `client-v2` is a rewrite of the original Java client, and `jdbc-v2` is the JDBC driver rebuilt on top of it. The older `clickhouse-client` and `clickhouse-jdbc` artifacts still exist and still work.

The reason given is migration pressure. The previous client version required a significant rewrite, so rather than break anyone's work in place, the maintainers created a new one and left the old one running. The JDBC driver needed changes both to work with the new client and to comply more closely with the JDBC specification, so it got its own V2 as well. V2 will replace the old version and keep the artifact name.

Underneath, both clients speak the same wire protocol. The Java client is the core component and talks to ClickHouse over HTTP, and the JDBC driver is a spec-compliant layer on top of the client API rather than a separate network stack. That is why a JDBC change and a client change often land together.

The feature table is the migration decision

A comparison table in the README lists each capability against Client V2 and Client V1, and it is the most useful thing in the document. Both generations support HTTP connections, LZ4 compression in three places (server responses, client requests, and the HTTP connection itself), HTTPS, mutual TLS client certificates, an authenticated HTTP proxy, connection pooling, named parameters, retry on failure, log comments, session roles, SSL client authentication and session timezone.

Then the differences split cleanly. Java Object SerDe is marked as V2 only, which is the main thing the rewrite buys you. Failover, load balancing and server auto-discovery are all marked as V1 only.

Those three losses are the cost of the rewrite, and they are not small for anyone running a multi-node ClickHouse cluster. Server auto-discovery in particular means a V2 application has to know its node list from configuration rather than learning it from the server. If you are evaluating this for a production cluster, that row decides the answer before anything else does.

Installing from Maven Central, and the classifier trap

Everything is published as ordinary Maven artifacts under `com.clickhouse`, with releases on Maven Central and nightly builds on a Sonatype snapshots repository at `https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/`.

The coordinate for the current client is `com.clickhouse:client-v2`, and the JDBC driver is `com.clickhouse:clickhouse-jdbc`. There is also an R2DBC driver at `com.clickhouse:clickhouse-r2dbc`, and a unified client at `com.clickhouse:clickhouse-client` alongside `com.clickhouse:clickhouse-http-client` for the older generation.

The classifier change in version 0.9.0 is the part that breaks builds. Three classifiers on `clickhouse-jdbc` are being retired: `shaded`, `http` and `shaded-all`. The first and last are replaced by the `all` classifier, which the README says will contain all required classes. The `http` classifier has no stated replacement. The base artifact `com.clickhouse:clickhouse-jdbc` itself remains untouched, so a build that never named a classifier is unaffected.

A repository that also contains the older code paths

The top level directory listing explains a lot about how the project is organised during a transition. You have `client-v2/`, `jdbc-v2/`, `clickhouse-client/`, `clickhouse-jdbc/`, `clickhouse-http-client/`, `clickhouse-r2dbc/` and `clickhouse-tcp-client/` as separate module directories, plus `migration-helpers/` and a `history/` directory.

Examples are split the same way. There are `examples/client-v2/`, `examples/client/`, `examples/jdbc/`, `examples/jdbc-v2-json-processors/`, `examples/r2dbc/`, and a Spring demo under `examples/demo-spring-service`. Two example directories suggest current interest in Arrow and JSON: `examples/client-v2-apache-arrow/` and `examples/client-v2-json-processors/`, with matching `jdbc-v2-json-processors/`.

Build infrastructure is Maven with a root `pom.xml`, a `release.sh`, and a `build_examples.sh` for compiling the example modules separately. Coverage output is handled by `jacoco-report-generator.mjs`, and there is a `performance/` directory, so the project does carry its own benchmark scaffolding even though the README reports no numbers.

Version numbers that do not sort the way you expect

The release sequence is worth reading carefully. v0.9.9 was published on 2026-08-25, v0.10.0 on 2026-08-17, and v0.11.0-rc1 on 2026-10-02.

So 0.9.9 came out after 0.10.0, and the newest artifact is a release candidate rather than a final release. That pattern suggests 0.9.x was maintained as a line while 0.10.0 moved forward, and if you pin a version you should check whether you want the maintenance line or the newer one rather than assuming the highest number is the most current release.

The deprecation table lists ClickHouse Java v1 with a version of TBC and a comment that it will be deprecated in 2025. That date has passed in the repository's own terms without the table being updated, so treat the V1 timeline as unspecified. The last push was on 2026-10-16, after v0.11.0-rc1, so the migration does not appear to be finished.

Licensing is Apache-2.0, and the repository carries an explicit `LICENSE` file plus an `AI_POLICY.md` and `SECURITY.md`.

Against the community JDBC driver and against HTTP yourself

The realistic alternatives are a third party JDBC driver for ClickHouse, or no driver at all.

A community driver wins on one axis: it is a single implementation, so there is no V1 to V2 question and no classifier retirement to plan around. It loses on the axis this repository is built around. The ClickHouse client is supported by the ClickHouse team, it speaks LZ4 compression on both request and response, and it carries session roles, log comments and session timezone as first class settings rather than as query parameters you assemble yourself. Choosing the community driver means accepting that the server behaviours it covers will track your queries rather than the server's own releases.

The other alternative is to skip JDBC entirely and call the HTTP interface with your own HTTP client, mapping rows yourself. For a narrow ingestion job this is a few dozen lines and no dependency at all. It also means giving up retries, connection pooling and failover, all of which the README lists as built in, and reimplementing the type mapping for every column type ClickHouse adds.

R2DBC is the third option for reactive stacks, and it is maintained here rather than elsewhere, which is unusual for a database driver and removes one reason to look outside.

Editorial conclusion

Choose client-v2 for new work if you want Java object serialization and named parameters and can live without failover, load balancing and server auto-discovery. Stay on client-v1 and jdbc if any of those three matter to you, because the README marks V1 for deprecation but has not yet published a replacement for them in V2. Verify first which artifact your build resolves, since the 0.9.0 classifier retirement removed the shaded, http and shaded-all variants of clickhouse-jdbc.

Frequently asked questions

Official sources

1. ClickHouse/clickhouse-java on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases