From 33490f5700f17549632f0e5a80ded87613d1358f Mon Sep 17 00:00:00 2001 From: Sergey Chernov Date: Wed, 1 Jul 2026 11:54:38 -0700 Subject: [PATCH 1/2] Updated version and changelog --- CHANGELOG.md | 128 ++++++++++++++++-- examples/client-v2-json-processors/pom.xml | 2 +- examples/client-v2/pom.xml | 2 +- examples/client/pom.xml | 4 +- .../demo-kotlin-service/gradle.properties | 2 +- examples/demo-service/gradle.properties | 2 +- examples/jdbc-v2-json-processors/pom.xml | 2 +- examples/jdbc/pom.xml | 2 +- .../pom.xml | 2 +- performance/pom.xml | 2 +- pom.xml | 10 +- 11 files changed, 128 insertions(+), 30 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 320805a55..84be7b59b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -## 0.10.0 +## 0.10.0-rc1 ### Breaking Changes @@ -17,33 +17,131 @@ (https://github.com/ClickHouse/clickhouse-java/issues/2652, https://github.com/ClickHouse/clickhouse-java/issues/2825) -### Breaking Changes +- **[client-v2]** `Client.Builder#build()` now throws `ClientMisconfigurationException` instead of + `IllegalArgumentException` for authentication and SSL misconfiguration (missing credentials, conflicting + authentication methods, missing client certificate when SSL authentication is enabled, and trust store used together + with a client certificate). Callers that relied on catching `IllegalArgumentException` from `build()` for these cases + must catch `ClientMisconfigurationException` (which extends `RuntimeException` via `ClientException`). (https://github.com/ClickHouse/clickhouse-java/pull/2812) + +- **[client-v2]** Combining `setUsername(...)` + `setPassword(...)` with a custom `Authorization` HTTP header ( + `httpHeader(HttpHeaders.AUTHORIZATION, ...)`) now fails at `Client.Builder#build()` with + `ClientMisconfigurationException` unless HTTP Basic authentication is explicitly disabled via + `useHTTPBasicAuth(false)`. Previously this combination was accepted and the custom `Authorization` header overrode the + ClickHouse user/password headers at request time. (https://github.com/ClickHouse/clickhouse-java/pull/2812) + +- **[client-v2]** The `access_token` configuration property (set via `Client.Builder#setAccessToken(String)` or directly + through `setOption`) is now actually applied to outgoing requests as the `Authorization` HTTP header value verbatim. + Previously the value was stored under `access_token` but never sent on the wire, so providing it alone had no effect + on authentication. Callers must include the scheme prefix themselves (e.g. `setAccessToken("Bearer ")`), or use + `useBearerTokenAuth(String)` which prepends `Bearer ` automatically. (https://github.com/ClickHouse/clickhouse-java/pull/2812) + +- **[client-v2]** `Client.Builder#useBearerTokenAuth(String)` now stores the bearer token under the `access_token` + configuration key (with the `Bearer ` prefix) instead of writing it directly into `http_header_authorization`. The + HTTP wire format is unchanged, but the token is no longer observable through `Client#getReadOnlyConfig()` under the + `http_header_authorization` key. (https://github.com/ClickHouse/clickhouse-java/pull/2812) -- **[client-v2]** `Client.Builder#build()` now throws `ClientMisconfigurationException` instead of `IllegalArgumentException` for authentication and SSL misconfiguration (missing credentials, conflicting authentication methods, missing client certificate when SSL authentication is enabled, and trust store used together with a client certificate). Callers that relied on catching `IllegalArgumentException` from `build()` for these cases must catch `ClientMisconfigurationException` (which extends `RuntimeException` via `ClientException`). +### New Features -- **[client-v2]** Combining `setUsername(...)` + `setPassword(...)` with a custom `Authorization` HTTP header (`httpHeader(HttpHeaders.AUTHORIZATION, ...)`) now fails at `Client.Builder#build()` with `ClientMisconfigurationException` unless HTTP Basic authentication is explicitly disabled via `useHTTPBasicAuth(false)`. Previously this combination was accepted and the custom `Authorization` header overrode the ClickHouse user/password headers at request time. +- **[jdbc-v2, client-v2]** Implemented SSL modes configuration. Now it is possible to set `ssl_mode` to `DISABLED`, + `TRUST`, `VERIFY_CA` and `STRICT`. Note for V1 users: `NONE` is supported only by JDBC driver and mapped to `TRUST`. + Please migrate to the new naming. + - Examples for client-v2 https://github.com/ClickHouse/clickhouse-java/blob/main/examples/client-v2/src/main/java/com/clickhouse/examples/client_v2/SSLExamples.java + - Examples for jdbc-v2 https://github.com/ClickHouse/clickhouse-java/blob/main/examples/jdbc/src/main/java/com/clickhouse/examples/jdbc/SSLExamples.java + (https://github.com/ClickHouse/clickhouse-java/pull/2874, https://github.com/ClickHouse/clickhouse-java/issues/2389, + https://github.com/ClickHouse/clickhouse-java/issues/2309, https://github.com/ClickHouse/clickhouse-java/issues/2819) + +- **[jdbc-v2, client-v2] (experimental)** Implemented standalone readers for `JSONEachRow` to provide scaffold for + reading this format. Additionally, it gives a way to map `Json` columns to custom types using JDBC driver. See examples + in https://github.com/ClickHouse/clickhouse-java/tree/main/examples/jdbc-v2-json-processors and https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2-json-processors. + (https://github.com/ClickHouse/clickhouse-java/pull/2871) + +- **[client-v2]** Added `Session` API to encapsulate and manage ClickHouse session settings (`session_id`, + `session_check`, `session_timeout`, `session_timezone`) as a reusable object. The `Session` instance can be applied to + any request settings using `applyTo()`, and session state can be cleared via `clearSession()`. Additionally, added + `resetOption(String)` to `InsertSettings`, `QuerySettings`, and `CommonSettings` to allow removing specific settings. + Settings explicitly set to `null` will not be sent to the server, which is useful for overriding global settings. + (https://github.com/ClickHouse/clickhouse-java/pull/2810) + +- **[client-v2]** Added runtime credential update APIs on `Client`: `updateUserAndPassword(String, String)`, + `updateAccessToken(String)`, and `updateBearerToken(String)`. Subsequent requests on the same `Client` instance use + the new credentials without rebuilding the client. The authentication method is fixed at construction time; calling a + runtime updater that does not match the configured method throws `ClientMisconfigurationException`. See + `docs/authentication.md` for details and migration guidance. (https://github.com/ClickHouse/clickhouse-java/pull/2812) + +- **[jdbc-v2]** Added `cluster_name` configuration property to specify a target cluster for statements like `KILL QUERY` + that require an `ON CLUSTER` clause to execute across all + nodes. (https://github.com/ClickHouse/clickhouse-java/issues/2837) + +- **[client-v2, jdbc-v2]** Added support for ClickHouse `Geometry` type for ClickHouse `25.11+`, where `Geometry` + changed from a `String` alias to `Variant(Point, Ring, LineString, MultiLineString, Polygon, MultiPolygon)` (client + still compatible with older versions). Includes client read/write handling and JDBC type mapping for retrieving and + inserting geometry values. Current writes infer the target geometry variant from array nesting depth, so `Ring` vs + `LineString` and `Polygon` vs `MultiLineString` are not yet distinguishable through the generic `Geometry` write + path. (https://github.com/ClickHouse/clickhouse-java/pull/2815) + +- **[jdbc-v2]** `ResultSet#getObject(int|String, Map>)` now accepts ClickHouse type names as map keys + in addition to the JDBC `SQLType` names it has always accepted. Only unwrapped type names are used for the lookup — + `Nullable(...)` and `LowCardinality(...)` wrappers are stripped and do not affect resolution, so a key like `"Int32"` + matches both `Int32` and `Nullable(Int32)` columns; keys like `"Nullable(Int32)"` are not recognized. Lookup order is + the `ClickHouseDataType` enum name (e.g. `"Int32"`, `"String"`, `"DateTime"`) then the JDBC `SQLType` name (e.g. + `"INTEGER"`, `"VARCHAR"`, `"TIMESTAMP"`); a missing entry leaves the value uncoerced. The feature is supported for + primitive ClickHouse types only — `Array`, `Tuple`, `Map`, `Nested`, and geometry types are not supported and continue + to be returned in their native form regardless of the user-supplied map. Existing maps keyed only by JDBC `SQLType` + names continue to work unchanged. (https://github.com/ClickHouse/clickhouse-java/pull/2865) + + - **[jdbc-v2]** Added support of custom mapping for JDBC types. Mainly used in cases when big integers should be + presented as string. Use `DriverProperties.JDBC_TYPE_MAPPINGS` (`jdbc_type_mappings`) and set needed type mapping + as `key=value[,]` list (For example, `Int32=Long,UInt64=String`). Deprecation notice: V1 property `typeMappings` is + supported but will be removed. Please migrate to the new property. + (https://github.com/ClickHouse/clickhouse-java/issues/2858) -- **[client-v2]** The `access_token` configuration property (set via `Client.Builder#setAccessToken(String)` or directly through `setOption`) is now actually applied to outgoing requests as the `Authorization` HTTP header value verbatim. Previously the value was stored under `access_token` but never sent on the wire, so providing it alone had no effect on authentication. Callers must include the scheme prefix themselves (e.g. `setAccessToken("Bearer ")`), or use `useBearerTokenAuth(String)` which prepends `Bearer ` automatically. +### Improvements -- **[client-v2]** `Client.Builder#useBearerTokenAuth(String)` now stores the bearer token under the `access_token` configuration key (with the `Bearer ` prefix) instead of writing it directly into `http_header_authorization`. The HTTP wire format is unchanged, but the token is no longer observable through `Client#getReadOnlyConfig()` under the `http_header_authorization` key. +- **[jdbc-v2, client-v2]** Added support of hostnames with underscore (`_`) in them. Now it is possible to specify endpoint +like `ch_db_01`. This is mostly used in k8s environment. (https://github.com/ClickHouse/clickhouse-java/issues/2792, + https://github.com/ClickHouse/clickhouse-java/issues/2753) -### New Features - -- **[client-v2]** Added `Session` API to encapsulate and manage ClickHouse session settings (`session_id`, `session_check`, `session_timeout`, `session_timezone`) as a reusable object. The `Session` instance can be applied to any request settings using `applyTo()`, and session state can be cleared via `clearSession()`. Additionally, added `resetOption(String)` to `InsertSettings`, `QuerySettings`, and `CommonSettings` to allow removing specific settings. Settings explicitly set to `null` will not be sent to the server, which is useful for overriding global settings. +### Updated Dependencies -- **[client-v2]** Added runtime credential update APIs on `Client`: `updateUserAndPassword(String, String)`, `updateAccessToken(String)`, and `updateBearerToken(String)`. Subsequent requests on the same `Client` instance use the new credentials without rebuilding the client. The authentication method is fixed at construction time; calling a runtime updater that does not match the configured method throws `ClientMisconfigurationException`. See `docs/authentication.md` for details and migration guidance. +- **[tests]** Bump org.postgresql:postgresql from 42.6.1 to 42.7.11 -- **[jdbc-v2]** Added `cluster_name` configuration property to specify a target cluster for statements like `KILL QUERY` that require an `ON CLUSTER` clause to execute across all nodes. (https://github.com/ClickHouse/clickhouse-java/issues/2837) +### Docs & Examples -- **[client-v2, jdbc-v2]** Added support for ClickHouse `Geometry` type for ClickHouse `25.11+`, where `Geometry` changed from a `String` alias to `Variant(Point, Ring, LineString, MultiLineString, Polygon, MultiPolygon)` (client still compatible with older versions). Includes client read/write handling and JDBC type mapping for retrieving and inserting geometry values. Current writes infer the target geometry variant from array nesting depth, so `Ring` vs `LineString` and `Polygon` vs `MultiLineString` are not yet distinguishable through the generic `Geometry` write path. (https://github.com/ClickHouse/clickhouse-java/pull/2815) +- **[client-v2]** Added example of working with `Apache Arrow` library using client. (https://github.com/ClickHouse/clickhouse-java/pull/2820) -- **[jdbc-v2]** `ResultSet#getObject(int|String, Map>)` now accepts ClickHouse type names as map keys in addition to the JDBC `SQLType` names it has always accepted. Only unwrapped type names are used for the lookup — `Nullable(...)` and `LowCardinality(...)` wrappers are stripped and do not affect resolution, so a key like `"Int32"` matches both `Int32` and `Nullable(Int32)` columns; keys like `"Nullable(Int32)"` are not recognized. Lookup order is the `ClickHouseDataType` enum name (e.g. `"Int32"`, `"String"`, `"DateTime"`) then the JDBC `SQLType` name (e.g. `"INTEGER"`, `"VARCHAR"`, `"TIMESTAMP"`); a missing entry leaves the value uncoerced. The feature is supported for primitive ClickHouse types only — `Array`, `Tuple`, `Map`, `Nested`, and geometry types are not supported and continue to be returned in their native form regardless of the user-supplied map. Existing maps keyed only by JDBC `SQLType` names continue to work unchanged. +- **[repo]** Added a contribution guide. Please review and send us your feedback. (https://github.com/ClickHouse/clickhouse-java/pull/2859) ### Bug Fixes -- **[jdbc-v2]** Fixed `Statement.cancel()` throwing `SESSION_IS_LOCKED` when the statement was running inside a ClickHouse session. The driver now accepts `session_id`, `session_check`, and `session_timeout` as first-class connection properties and correctly suppresses them when issuing a `KILL QUERY` during cancellation. This ensures the cancellation request runs outside the session and no longer contends with the running query for the session lock. (https://github.com/ClickHouse/clickhouse-java/issues/2690, https://github.com/ClickHouse/clickhouse-java/issues/2881) +- **[jdbc-v2, client-v2]** Fixed error handling for responses that not a ClickHouse error, like `404` response. (https://github.com/ClickHouse/clickhouse-java/issues/2803) + +- **[jdbc-v2, client-v2]** Fixed setting `null` as password. Previously it was converted to `null` literal. Still we recommend +passing empty string. (https://github.com/ClickHouse/clickhouse-java/pull/2809) + +- **[jdbc-v2, client-v2]** Fixed `ClickHouseBinaryFormatReader::getBigDecimal` silently truncating big integer. +(https://github.com/ClickHouse/clickhouse-java/issues/2748) + +- **[jdbc-v2, client-v2]** Fixed handling `NULL` values to `Variant` and `Dynamic` columns. Previously indicator +of `NULL` was not set and read. (https://github.com/ClickHouse/clickhouse-java/issues/2789, https://github.com/ClickHouse/clickhouse-java/issues/2791) + +- **[client-v2]** Fixed timeunit inconsistency of `executionTimeout` parameter. Previously was saved in milliseconds but +used as value in seconds. (https://github.com/ClickHouse/clickhouse-java/issues/2358) + +- **[jdbc-v2]** Fixed `Statement.cancel()` throwing `SESSION_IS_LOCKED` when the statement was running inside a + ClickHouse session. The driver now accepts `session_id`, `session_check`, and `session_timeout` as first-class + connection properties and correctly suppresses them when issuing a `KILL QUERY` during cancellation. This ensures the + cancellation request runs outside the session and no longer contends with the running query for the session + lock. (https://github.com/ClickHouse/clickhouse-java/issues/2690, https://github.com/ClickHouse/clickhouse-java/issues/2881) + +- **[client-v2]** Fixed inconsistent use of `executionTimeout` parameter in `Client` component. The timeout was + previously set in milliseconds but mistakenly retrieved and used in seconds in some places. Now it correctly uses + milliseconds consistently. (https://github.com/ClickHouse/clickhouse-java/issues/2358) + +- **[jdbc-v2]** Added option to specify cluster name for operations on cluster. One of them is `KILL QUERY .. ON CLUSTER `. + Use `DriverProperties.CLUSTER_NAME` (`jdbc_cluster_name`) to define name of the cluster to be used in such queries. + (https://github.com/ClickHouse/clickhouse-java/issues/2837) -- **[client-v2]** Fixed inconsistent use of `executionTimeout` parameter in `Client` component. The timeout was previously set in milliseconds but mistakenly retrieved and used in seconds in some places. Now it correctly uses milliseconds consistently. (https://github.com/ClickHouse/clickhouse-java/issues/2358) +- **[jdbc-v2, client-v2]** Fixed writing nullable marker for nested `Tuple` and `Map values. (https://github.com/ClickHouse/clickhouse-java/issues/2721) ## 0.9.8 diff --git a/examples/client-v2-json-processors/pom.xml b/examples/client-v2-json-processors/pom.xml index 05766ae0e..d952a019e 100644 --- a/examples/client-v2-json-processors/pom.xml +++ b/examples/client-v2-json-processors/pom.xml @@ -17,7 +17,7 @@ UTF-8 17 - 0.9.8-SNAPSHOT + 0.10.0-rc1-SNAPSHOT 2.22.0 2.14.0 2.0.17 diff --git a/examples/client-v2/pom.xml b/examples/client-v2/pom.xml index b3111c640..ad63cbc61 100644 --- a/examples/client-v2/pom.xml +++ b/examples/client-v2/pom.xml @@ -54,7 +54,7 @@ UTF-8 UTF-8 - 0.9.8-SNAPSHOT + 0.10.0-rc1-SNAPSHOT 3.8.1 diff --git a/examples/client/pom.xml b/examples/client/pom.xml index 55e0e354b..f3903a11d 100644 --- a/examples/client/pom.xml +++ b/examples/client/pom.xml @@ -40,9 +40,9 @@ UTF-8 UTF-8 - 0.9.8-SNAPSHOT + 0.10.0-rc1-SNAPSHOT - + 5.2.1 diff --git a/examples/demo-kotlin-service/gradle.properties b/examples/demo-kotlin-service/gradle.properties index 910243552..38bb7b1ca 100644 --- a/examples/demo-kotlin-service/gradle.properties +++ b/examples/demo-kotlin-service/gradle.properties @@ -3,4 +3,4 @@ ktor_version=2.3.12 kotlin_version=2.0.20 logback_version=1.4.14 -ch_java_client_version=0.9.8 \ No newline at end of file +ch_java_client_version=0.10.0-rc1 \ No newline at end of file diff --git a/examples/demo-service/gradle.properties b/examples/demo-service/gradle.properties index 17c78e75c..91d6540f6 100644 --- a/examples/demo-service/gradle.properties +++ b/examples/demo-service/gradle.properties @@ -1,2 +1,2 @@ -ch_java_client_version=0.9.8 \ No newline at end of file +ch_java_client_version=0.10.0-rc1 \ No newline at end of file diff --git a/examples/jdbc-v2-json-processors/pom.xml b/examples/jdbc-v2-json-processors/pom.xml index 6c309a573..5e4ce9243 100644 --- a/examples/jdbc-v2-json-processors/pom.xml +++ b/examples/jdbc-v2-json-processors/pom.xml @@ -17,7 +17,7 @@ UTF-8 17 - 0.9.8-SNAPSHOT + 0.10.0-rc1-SNAPSHOT 2.22.0 2.14.0 2.0.17 diff --git a/examples/jdbc/pom.xml b/examples/jdbc/pom.xml index 0bfdce4d0..22cf27d39 100644 --- a/examples/jdbc/pom.xml +++ b/examples/jdbc/pom.xml @@ -54,7 +54,7 @@ UTF-8 UTF-8 - 0.9.8-SNAPSHOT + 0.10.0-rc1-SNAPSHOT 4.0.3 5.2.1 diff --git a/examples/r2dbc/clickhouse-r2dbc-spring-webflux-sample/pom.xml b/examples/r2dbc/clickhouse-r2dbc-spring-webflux-sample/pom.xml index 4c39b3184..b8d644a12 100644 --- a/examples/r2dbc/clickhouse-r2dbc-spring-webflux-sample/pom.xml +++ b/examples/r2dbc/clickhouse-r2dbc-spring-webflux-sample/pom.xml @@ -14,7 +14,7 @@ 1.8 1.8 - 0.9.8-SNAPSHOT + 0.10.0-rc1-SNAPSHOT 2.7.18 diff --git a/performance/pom.xml b/performance/pom.xml index 7f25f9a27..9e0bbdcb6 100644 --- a/performance/pom.xml +++ b/performance/pom.xml @@ -15,7 +15,7 @@ 5.3.1 2.0.17 - 0.9.8-SNAPSHOT + 0.10.0-rc1-SNAPSHOT 1.37 2.0.2 diff --git a/pom.xml b/pom.xml index 69f35d6c5..f6a5257dc 100644 --- a/pom.xml +++ b/pom.xml @@ -29,10 +29,10 @@ - zhicwu - Zhichun Wu - zhicwu@gmail.com - +8 + sergey_chernov + Sergey Chernov + sergey.chernov@clickhouse.com + -8 @@ -69,7 +69,7 @@ - 0.9.8-SNAPSHOT + 0.10.0-rc1-SNAPSHOT 2026 UTF-8 UTF-8 From 73156f8c72675ec61c47ae69c5ea0af525d9fccd Mon Sep 17 00:00:00 2001 From: Sergey Chernov Date: Wed, 1 Jul 2026 11:58:35 -0700 Subject: [PATCH 2/2] Added script to build examples --- build_examples.sh | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100755 build_examples.sh diff --git a/build_examples.sh b/build_examples.sh new file mode 100755 index 000000000..15c530eed --- /dev/null +++ b/build_examples.sh @@ -0,0 +1,8 @@ +#!/bin/sh +LIB_VER=$(grep '' pom.xml | sed -e 's|[[:space:]]*<[/]*revision>[[:space:]]*||g') +find `pwd`/examples -type f -name pom.xml -exec sed -i -e "s|\(\).*\(<\)|\1$LIB_VER\2|g" {} \; +for d in $(ls -d `pwd`/examples/*/); do \ + if [ -e $d/pom.xml ]; then cd $d && mvn --batch-mode --no-transfer-progress clean compile; fi; + if [ -e $d/gradlew ]; then cd $d && ./gradlew clean build; fi; +done +