diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 022d27155..4286cbe30 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,10 +2,6 @@ name: Release on: workflow_dispatch: - inputs: - version: - description: "Release version" - required: true env: CH_VERSION: "25.3" @@ -15,11 +11,16 @@ jobs: name: "Build and Publish Artifact" runs-on: "ubuntu-latest" - permissions: write-all + permissions: + contents: write steps: - name: Check out Git repository uses: actions/checkout@v4 + - name: Read release version + id: version + shell: bash + run: echo "version=$(cat VERSION)" >> "$GITHUB_OUTPUT" - name: Install JDK and Maven uses: actions/setup-java@v4 with: @@ -28,6 +29,11 @@ jobs: 8 17 cache: 'maven' + server-id: central + server-username: MAVEN_USERNAME + server-password: MAVEN_PASSWORD + gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }} + gpg-passphrase: MAVEN_GPG_PASSPHRASE - name: Setup Toolchain shell: bash run: | @@ -48,43 +54,34 @@ jobs: EOF - name: Update Configuration run: | - sed -i 's|.*|${{ github.event.inputs.version }}|g' pom.xml + sed -i 's|.*|${{ steps.version.outputs.version }}|g' pom.xml find . -type f -name "simplelogger.*" -exec rm -fv '{}' \; - name: Release Maven package - uses: samuelmeuli/action-maven-publish@v1 - with: - maven_profiles: release - maven_args: -q --batch-mode -DclickhouseVersion=${{ env.CH_VERSION }} - server_id: central - gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} - gpg_passphrase: ${{ secrets.GPG_PASSPHRASE }} - nexus_username: ${{ secrets.SONATYPE_TOKEN_USER }} - nexus_password: ${{ secrets.SONATYPE_TOKEN }} + env: + MAVEN_USERNAME: ${{ secrets.SONATYPE_TOKEN_USER }} + MAVEN_PASSWORD: ${{ secrets.SONATYPE_TOKEN }} + MAVEN_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} + run: mvn -q --batch-mode -P release -DclickhouseVersion=${{ env.CH_VERSION }} clean deploy - name: Release R2DBC 0.9.1 - uses: samuelmeuli/action-maven-publish@v1 - with: - directory: clickhouse-r2dbc - maven_profiles: release - maven_args: -q --batch-mode -Dr2dbc-spi.version=0.9.1.RELEASE -DclickhouseVersion=${{ env.CH_VERSION }} - server_id: central - gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} - gpg_passphrase: ${{ secrets.GPG_PASSPHRASE }} - nexus_username: ${{ secrets.SONATYPE_TOKEN_USER }} - nexus_password: ${{ secrets.SONATYPE_TOKEN }} + working-directory: clickhouse-r2dbc + env: + MAVEN_USERNAME: ${{ secrets.SONATYPE_TOKEN_USER }} + MAVEN_PASSWORD: ${{ secrets.SONATYPE_TOKEN }} + MAVEN_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} + run: mvn -q --batch-mode -P release -Dr2dbc-spi.version=0.9.1.RELEASE -DclickhouseVersion=${{ env.CH_VERSION }} clean deploy - name: Create Pre-release on Github - uses: "zhicwu/action-automatic-releases@latest" - with: - repo_token: "${{ secrets.GITHUB_TOKEN }}" - automatic_release_tag: "v${{ github.event.inputs.version }}" - prerelease: true - title: "Release v${{ github.event.inputs.version }}" - files: | - LICENSE - clickhouse-client/target/clickhouse*.jar - clickhouse-data/target/clickhouse*.jar - clickhouse-http-client/target/clickhouse*.jar - clickhouse-jdbc/target/clickhouse*.jar - clickhouse-jdbc/target/bundle/clickhouse*.jar - clickhouse-r2dbc/target/clickhouse*.jar - client-v2/target/client-v2*.jar + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh release create "v${{ steps.version.outputs.version }}" \ + --prerelease \ + --title "Release v${{ steps.version.outputs.version }}" \ + LICENSE \ + clickhouse-client/target/clickhouse*.jar \ + clickhouse-data/target/clickhouse*.jar \ + clickhouse-http-client/target/clickhouse*.jar \ + clickhouse-jdbc/target/clickhouse*.jar \ + clickhouse-jdbc/target/bundle/clickhouse*.jar \ + clickhouse-r2dbc/target/clickhouse*.jar \ + client-v2/target/client-v2*.jar \ jdbc-v2/target/jdbc-v2*.jar diff --git a/CHANGELOG.md b/CHANGELOG.md index 320805a55..dfd2c8826 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,6 @@ -## 0.10.0 +## 0.10.0-rc1 + +[Release Migration Guide](docs/releases/0_10_0.md) ### Breaking Changes @@ -12,38 +14,133 @@ method) is no longer guaranteed to be accurate for INSERT statements when the server runs them asynchronously, and parsing/data errors in the INSERT body may not surface synchronously as a `SQLException`. Previously these were accurate because inserts were forced to be synchronous (see also https://github.com/ClickHouse/ClickHouse/issues/57768). - To restore the previous behavior, set `async_insert=0` (or `wait_for_async_insert=1`) per connection or statement. + To restore the previous behavior, set `async_insert=0` (or `wait_for_async_insert=1`) per connection as server setting. Read more about asynchronous insert: https://clickhouse.com/docs/optimize/asynchronous-inserts. (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`). +- **[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 user/password 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]** 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) -- **[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. +### New Features -- **[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. +- **[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] (beta)** 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]** `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. +### Improvements -### New Features +- **[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) -- **[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) + +- **[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]** 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/VERSION b/VERSION new file mode 100644 index 000000000..50687903a --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.10.0-rc1 \ No newline at end of file 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 + diff --git a/docs/releases/0_10_0.md b/docs/releases/0_10_0.md new file mode 100644 index 000000000..e8e748602 --- /dev/null +++ b/docs/releases/0_10_0.md @@ -0,0 +1,85 @@ +# Release 0.10.0 + +# Migration Guide + +## JDBC-V2: `async_insert=1` not Set by Default + +The previous version of the JDBC driver set `async_insert=0`, effectively making any insert operation synchronous. +This was done to get the insert summary that is then returned by the family of `java.sql.Statement#executeUpdate(java.lang.String)` methods. +Now these methods will not return an accurate number of records (in most cases `0`) if the server is using `async_insert=1`. + +Set `clickhouse_setting_wait_for_async_insert=1` at the connection level to make the server wait for the async insert to complete. In this +case the client will get a response and return control once the operation is done on the server side. However, this option does not produce an accurate summary. + +Set `clickhouse_setting_async_insert=0` at the connection level (or pass it via the JDBC connection string) to fall back to synchronous inserts. + +See more about async inserts: https://clickhouse.com/docs/optimize/asynchronous-inserts + +## CLIENT-V2 & JDBC-V2: User/Password Credentials not Allowed with Custom `Authorization` HTTP Header + +The client builder throws an exception if both user credentials and a custom `Authorization` header are set. This is done to prevent configuration +errors. Previously this combination was accepted and the custom `Authorization` header overrode the user/password at request time. + +If an application wants to use both mechanisms, we recommend creating separate Client instances for each authentication method. This will +also protect against using the default user credentials instead of the custom `Authorization` header. + + +## CLIENT-V2 & JDBC-V2: Access Token and Bearer Token Clarification + +There are two configuration parameters: +- `com.clickhouse.client.api.ClientConfigProperties#ACCESS_TOKEN` - accepts a raw value and passes it to the `Authorization` HTTP header. +- `com.clickhouse.client.api.ClientConfigProperties#BEARERTOKEN_AUTH` - adds `Bearer ` before the passed value and writes it to the `Authorization` HTTP header. + +The previous version had an issue that made the client ignore `ACCESS_TOKEN`. This is now fixed, and its value is passed to the `Authorization` HTTP header as is. +`com.clickhouse.client.api.ClientConfigProperties#BEARERTOKEN_AUTH` is processed as an alias to `com.clickhouse.client.api.Client.Builder#useBearerTokenAuth`, +which sets `com.clickhouse.client.api.ClientConfigProperties#ACCESS_TOKEN` to `Bearer ` + `token`. + +In most cases `com.clickhouse.client.api.ClientConfigProperties#BEARERTOKEN_AUTH` works better because it adds `Bearer `, so there is no need to do it in the application. + + +## CLIENT-V2 & JDBC-V2: `ClientConfigProperties.MAX_EXECUTION_TIME` (`executionTimeout`) is Always Treated in Milliseconds now + +There was a bug where the `executionTimeout` parameter was set in milliseconds but read in seconds. So it caused a bigger timeout than expected. + +If your application uses a workaround by setting lower values, then you need to adjust it before migrating to the new version. + +See also https://github.com/ClickHouse/clickhouse-java/pull/2841/changes. + +## CLIENT-V2 & JDBC-V2: SSLMode (`ssl_mode`) Changes + +There was an `ssl_mode` setting with two possible values, `none` and `strict`. It was ignored in V2 for a long time, until now we are re-introducing it. + +The most important change is that V1's `none` maps to `TRUST` in the V2 client and driver because it matches the trust-all logic. There was a problem enabling encryption +with self-signed certificates. `none` is still supported by JDBC (only) and is an alias for `TRUST`. Please migrate to the new value. + +The V2 client and driver now support these values: +- `DISABLED` - disables encryption. Do not use it with HTTP. This makes sense only for TCP, where the protocol doesn't provide encryption. HTTP has HTTPS for that. +- `TRUST` - valid for all protocols. Means encryption only. +- `VERIFY_CA` - valid for all protocols. Makes the client verify only the CA signature. No identity verification. +- `STRICT` - valid for all protocols. Default when HTTPS is used. Means complete verification of the server identity. + + +## JDBC-V2: **Deprecation** of `custom_http_params` and `custom_settings` + +We still see usage of `custom_http_params` and `custom_settings`, which comes from V1 of the client and JDBC driver. + +Please migrate to using the `com.clickhouse.client.api.ClientConfigProperties#SERVER_SETTING_PREFIX` (`clickhouse_setting_`) prefix because +- it is a more solid way to pass settings with a list of values (we had an issue parsing complex properties when they were used within `custom_http_params`). +- it makes the configuration clearer to understand, as it clearly belongs to server-side settings. + + +## JDBC-V2: **Deprecation** of `use_server_time_zone_for_dates` + +The driver does not apply a timezone to `Date` values anymore, as they have no such information stored in the database. + + +## JDBC-V2: **Deprecation** of `http_connection_provider` + +Driver V2 ignores this setting and uses only the available HTTP client. +There are plans to support other HTTP clients and protocols, but they will be configured a different way. + + +## JDBC-V2: **Deprecation** of `typeMappings` + +This property (not a feature) is deprecated. Please use `com.clickhouse.jdbc.DriverProperties#JDBC_TYPE_MAPPINGS` (`jdbc_type_mappings`) instead. + 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/jdbc-v2/docs/floating-point-precision.md b/jdbc-v2/docs/floating-point-precision.md new file mode 100644 index 000000000..d58141c7c --- /dev/null +++ b/jdbc-v2/docs/floating-point-precision.md @@ -0,0 +1,103 @@ +# Floating-point precision in jdbc-v2 + +This note documents how `Float32` and `Float64` values behave when written through the +`jdbc-v2` driver, why a `Float32` value can come back differing by up to one ULP, and how +tests should assert floating-point round-trips. + +## Background + +`PreparedStatement` parameters in `jdbc-v2` are **not** sent in ClickHouse `RowBinary` +form. Instead the driver serializes each parameter into a **textual SQL literal** and +substitutes it into the statement before sending it to the server +(`com.clickhouse.jdbc.PreparedStatementImpl#encodeObject`). + +For numeric primitives there is no dedicated branch, so the value falls through to the +default rendering: + +```java +return SQLUtils.escapeSingleQuotes(x.toString()); +``` + +This means: + +- `setFloat(i, x)` → `Float.toString(x)` (e.g. `-3.402823E38`) +- `setDouble(i, x)` → `Double.toString(x)` (e.g. `-1.7976931348623157E308`) + +`Float.toString` / `Double.toString` produce the *shortest* decimal string that round-trips +back to the **same** value *of that width* (`Float.parseFloat` for a float, `Double.parseDouble` +for a double). + +## Why a `Float32` can shift by one ULP + +When the server reads a decimal literal into a `Float32` column it parses it as `Float64` +first and then narrows the result to `Float32`. That is a **double rounding**: + +``` +decimal text -> Float64 (round #1) -> Float32 (round #2) +``` + +The shortest decimal emitted by `Float.toString` is only guaranteed to round-trip via a +**single** `decimal -> Float32` rounding. Routing it through `Float64` first can land on an +adjacent `Float32` value. The error is bounded by **one ULP** of the `Float32`, and in +practice only shows up for extreme magnitudes where the ULP is large. + +Observed example: + +| Java value inserted | Text sent | Value read back | +| ------------------- | ------------- | ----------------- | +| `-3.402823E38f` | `-3.402823E38`| `-3.4028229E38f` | + +`Float64` columns are **not** affected: the literal is parsed straight to `Float64` with a +single rounding, and `Double.toString` already round-trips exactly through that path. + +## Read side + +On retrieval the binary reader returns boxed primitives that mirror the column type +(`com.clickhouse.client.api.data_formats.internal.BinaryStreamReader`): + +| Column type | `getObject` returns | +| ----------- | ------------------- | +| `Float32` | `java.lang.Float` | +| `Float64` | `java.lang.Double` | + +So `ResultSet#getObject("float32")` is a `Float`, and `getObject("float64")` is a `Double`. + +## Implications for callers + +- A `Float32` written via `setFloat` may read back differing by up to one ULP. If you need + bit-exact `Float32` round-trips, avoid the text path — for example insert through the + `client-v2` binary writer, or store the value in a `Float64` column. +- `Float64` written via `setDouble` round-trips exactly. + +## Testing guidance + +Floating-point round-trips should not be asserted with exact equality for `Float32`. Use a +one-ULP tolerance for `Float32` and exact equality for `Float64`: + +```java +// Float32: allow up to one ULP because of decimal -> Float64 -> Float32 double rounding +assertEquals(rs.getFloat("float32"), expected32, Math.ulp(expected32)); + +// Float64: exact +assertEquals(rs.getDouble("float64"), Double.valueOf(expected64)); +``` + +The same tolerance applies when comparing the boxed `Float` returned by `getObject`: + +```java +Object actual32 = rs.getObject("float32"); +assertTrue(actual32 instanceof Float); +assertEquals((float) (Float) actual32, expected32, Math.ulp(expected32)); +``` + +See `com.clickhouse.jdbc.JdbcDataTypeTests#testFloatTypes` for a data-set-driven example +that exercises minimum, maximum, zero, unit, subnormal, constant, and random values. + +## Related: ClickHouse Cloud read-after-write + +`JdbcDataTypeTests` writes test rows and reads them back. On ClickHouse Cloud, separate +connections may be routed to different replicas, so a value written on one connection is not +guaranteed to be immediately visible to a `SELECT` on another. To keep these tests +deterministic without per-query consistency tuning, perform the write and the verifying read +on the **same** connection. `JdbcIntegrationTest#runQuery(String, Connection)` is provided to +run DDL on that same connection and avoid opening extra ones. 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..851d104f2 100644 --- a/pom.xml +++ b/pom.xml @@ -29,10 +29,14 @@ - zhicwu - Zhichun Wu - zhicwu@gmail.com - +8 + sergey_chernov + Sergey Chernov + sergey.chernov@clickhouse.com + + + mzitnik + Mark Zitnik + mark@clickhouse.com @@ -69,7 +73,7 @@ - 0.9.8-SNAPSHOT + 0.10.0-rc1-SNAPSHOT 2026 UTF-8 UTF-8 diff --git a/release.sh b/release.sh index e374ddba0..653180145 100755 --- a/release.sh +++ b/release.sh @@ -8,6 +8,9 @@ if [ -z "$RELEASE_VERSION" ]; then fi echo "Release version: $RELEASE_VERSION" +# write version to VERSION file (consumed by the release workflow) +printf '%s\n' "$RELEASE_VERSION" > VERSION + # update version in main pom.xml sed -i "s|.*<\/clickhouse-java.version>|${RELEASE_VERSION}<\/clickhouse-java.version>|g" pom.xml