Merge branch 'main' into 04/16/26/jdbc_override_settings

Author: chernser

.github/workflows/claude.yml

@@ -0,0 +1,57 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      github.event.sender.type != 'Bot' &&
+      (
+        contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association) ||
+        contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.review.author_association) ||
+        contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association)
+      ) &&
+      (
+        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+        (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+      )
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@b47fd721da662d48c5680e154ad16a73ed74d2e0 # v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'

.github/workflows/cross-repo-bug-relay.yml

@@ -0,0 +1,17 @@
+name: Relay bugs for cross-repo investigation
+
+# Relays newly-opened issues to ClickHouse/integrations-ai-playground for
+# cross-repo investigation.
+
+on:
+  issues:
+    types: [opened]
+
+permissions: {}
+
+jobs:
+  relay:
+    uses: ClickHouse/integrations-shared-workflows/.github/workflows/cross-repo-bug-relay.yml@main
+    secrets:
+      WORKFLOW_AUTH_PUBLIC_APP_ID: ${{ secrets.WORKFLOW_AUTH_PUBLIC_APP_ID }}
+      WORKFLOW_AUTH_PUBLIC_PRIVATE_KEY: ${{ secrets.WORKFLOW_AUTH_PUBLIC_PRIVATE_KEY }}

CHANGELOG.md

@@ -2,13 +2,21 @@
 
 ### Breaking Changes
 
-- **[jdbc-v2]** Hardcoded server setting `async_insert=0` is removed as well as others. This is done to 
-fix issue with overriding these settings and using client with read-only profiles. The change, first of all, makes 
-driver behavior to follow default what is set on server side (note: starting ClickHouse 26.3 `async_insert` is on by default).
-In second, this fix changes what number of affected rows returned by method like `java.sql.Statement.executeUpdate(java.lang.String)`. 
-Previously they return more accurate values because insert was synchronous, but in case of asynchronous insert it is not 
-guaranteed anymore (see also https://github.com/ClickHouse/ClickHouse/issues/57768). 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)
+- **[jdbc-v2]** Hardcoded server setting `async_insert=0` is removed as well as others. This is done to
+  fix issue with overriding these settings and using client with read-only profiles. The change, first of all, makes
+  driver behavior to follow default what is set on server side (note: starting ClickHouse 26.3 `async_insert` is on by default).
+  In second, this fix changes what number of affected rows returned by method like `java.sql.Statement.executeUpdate(java.lang.String)`.
+  Previously they return more accurate values because insert was synchronous, but in case of asynchronous insert it is not
+  guaranteed anymore (see also https://github.com/ClickHouse/ClickHouse/issues/57768). 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)
+
+### New Features
+
+- **[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)
+
+### Bug Fixes
+
+- **[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)
 
 ## 0.9.8
 

clickhouse-jdbc/src/test/java/com/clickhouse/jdbc/GenericJDBCTest.java

@@ -31,7 +31,7 @@ public void connectionTest() throws SQLException {
         }
     }
 
-    @Test
+    @Test(enabled = false) // skipped to be removed after reviewing tests.
     public void connectionWithPropertiesTest() throws SQLException {
         Properties properties = new Properties();
         properties.setProperty("user", "default");

client-v2/src/main/java/com/clickhouse/client/api/Client.java

@@ -667,10 +667,12 @@ public Builder setProxyCredentials(String user, String pass) {
         }
 
         /**
-         * Sets the maximum time for operation to complete. By default, it is set to 3 hours.
-         * @param timeout
-         * @param timeUnit
-         * @return
+         * Sets the maximum time for operation to complete. By default, it is unlimited.
+         * Value is saved in milliseconds always.
+         *
+         * @param timeout value of the timeout
+         * @param timeUnit time unit of the timeout value
+         * @return this instance
          */
         public Builder setExecutionTimeout(long timeout, ChronoUnit timeUnit) {
             this.configuration.put(ClientConfigProperties.MAX_EXECUTION_TIME.getKey(), String.valueOf(Duration.of(timeout, timeUnit).toMillis()));
@@ -1958,10 +1960,10 @@ private TableSchema getTableSchemaImpl(
         QuerySettings settings = new QuerySettings().setDatabase(database);
         try (QueryResponse response = operationTimeout == 0
                 ? query(describeQuery, queryParams, settings).get()
-                : query(describeQuery, queryParams, settings).get(getOperationTimeout(), TimeUnit.SECONDS)) {
+                : query(describeQuery, queryParams, settings).get(operationTimeout, TimeUnit.MILLISECONDS)) {
             return TableSchemaParser.readTSKV(response.getInputStream(), name, originalQuery, database);
         } catch (TimeoutException e) {
-            throw new ClientException("Operation has likely timed out after " + getOperationTimeout() + " seconds.", e);
+            throw new ClientException("Operation has likely timed out after " + getOperationTimeout() + " milliseconds.", e);
         } catch (ExecutionException e) {
             throw new ClientException("Failed to get table schema", e.getCause());
         } catch (ServerException e) {
@@ -2118,7 +2120,10 @@ public Map<String, String> getConfiguration() {
         return readOnlyConfig;
     }
 
-    /** Returns operation timeout in seconds */
+    /**
+     * Returns operation ({@link ClientConfigProperties#MAX_EXECUTION_TIME}) timeout value in milliseconds.
+     * @return timeout value in milliseconds.
+     */
     protected int getOperationTimeout() {
         return ClientConfigProperties.MAX_EXECUTION_TIME.getOrDefault(configuration);
     }

docs/ai-review.md

@@ -4,6 +4,8 @@ Use this guide across Cursor, Claude, Copilot, and other AI assistants when revi
 
 This repository contains Java libraries and drivers for ClickHouse, including shared data types, HTTP clients, the v2 client, JDBC drivers, and R2DBC integration.
 
+For a reusable review write-up format, use `docs/review-template.md`.
+
 ## Role
 
 Act as an experienced maintainer and reviewer of a public Java library.
@@ -169,6 +171,8 @@ When responding to a review request:
 3. Use file or symbol references where helpful.
 4. Keep any change summary brief and secondary.
 5. If no issues are found, say so explicitly and mention residual risk or testing gaps.
+6. Use `docs/review-template.md` when a structured review summary is helpful.
+7. End with exactly one verdict: `ready to merge`, `ready for human review`, or `need changes`.
 
 In the final summary, state:
 

docs/features.md

@@ -49,7 +49,7 @@ Compatibility-sensitive traits:
 - Schema and database context: Supports database selection through URL, `setSchema`, `USE`, and statement-level settings.
 - Non-transactional operation: Exposes ClickHouse-appropriate transaction behavior with auto-commit semantics and unsupported transactional features.
 - Statement execution: Supports `execute`, `executeQuery`, `executeUpdate`, large update counts, and forward-only/read-only statements.
-- Query cancellation and timeout: Supports JDBC query timeout handling and query cancellation through server-side `KILL QUERY`.
+- Query cancellation and timeout: Supports JDBC query timeout handling and query cancellation through server-side `KILL QUERY`, with optional JDBC `cluster_name` property support to add `ON CLUSTER '<name>'` for cluster-wide cancellation.
 - Batch execution: Supports batched statements and prepared-statement batches, including multi-row rewrite for eligible `INSERT ... VALUES` statements.
 - Prepared statements: Supports `?` parameters through client-side SQL rendering and validates that all parameters are bound before execution.
 - SQL parsing and classification: Classifies SQL to distinguish queries, updates, inserts, `USE`, and role-changing statements, with selectable parser backends.
@@ -67,6 +67,7 @@ Compatibility-sensitive traits:
 Compatibility-sensitive traits:
 
 - Prepared statements are client-side SQL rendering, not server-side prepared statements. Changes to literal encoding or placeholder parsing are externally visible behavior.
+- JDBC `cluster_name` is compatibility-sensitive for cancellation behavior: when configured, `Statement.cancel()` issues `KILL QUERY ON CLUSTER '<name>'`, and when omitted it falls back to a local `KILL QUERY`.
 - String parameters are escaped with backslash-based escaping: backslashes are doubled and single quotes are backslash-escaped before values are wrapped in single quotes.
 - `?` placeholder detection is SQL-aware and should not treat question marks inside quoted strings, quoted identifiers, comments, casts, or similar syntax as bind parameters.
 - String-like ClickHouse values have stable JDBC expectations: `String`, `FixedString`, and `Enum` values are returned as strings, while `UUID` is available both as `getString()` and `getObject(..., UUID.class)`.

docs/review-template.md

@@ -0,0 +1,67 @@
+# Review Template
+
+Use this template when writing a review summary for a pull request or patch.
+
+## Findings
+
+List findings first and order them by severity.
+
+### High
+
+- None.
+
+### Medium
+
+- None.
+
+### Low
+
+- None.
+
+## Human Review Instructions for Important Changes
+
+Ask a human reviewer to inspect important changes directly when the diff touches any of the following:
+
+- public API surface such as public classes, interfaces, methods, constructors, fields, or enums
+- behavioral compatibility such as defaults, retries, timeouts, parsing, serialization, formatting, or exception behavior
+- JDBC or R2DBC semantics, driver metadata, or type mappings
+- documented features in `docs/features.md`
+- security-sensitive code, authentication, credentials, or network-facing behavior
+- cross-module contracts where the same concept exists in multiple modules
+
+When human review is needed, call out the exact risk and what should be checked, for example:
+
+- verify that no public signature changed
+- verify that output format and serialized values are unchanged
+- verify that existing callers keep the same default behavior
+- verify that focused tests cover compatibility-sensitive paths
+- verify whether `docs/features.md` or other docs need updates
+
+## Verdict
+
+Choose exactly one verdict:
+
+- `ready to merge`: no blocking issues found and no additional human sign-off is needed beyond normal review flow
+- `ready for human review`: no blocking issues found by AI, but the change is important enough that a human should confirm compatibility, behavior, or product intent
+- `need changes`: blocking issues, regressions, compatibility risk, or missing validation were found and should be addressed before merge
+
+## Copy/Paste Template
+
+```md
+## Findings
+
+### High
+- None.
+
+### Medium
+- None.
+
+### Low
+- None.
+
+## Human Review Instructions for Important Changes
+- None.
+
+## Verdict
+`ready to merge`
+```

examples/client-v2-apache-arrow/.gitattributes

@@ -0,0 +1,12 @@
+#
+# https://help.github.com/articles/dealing-with-line-endings/
+#
+# Linux start script should use lf
+/gradlew        text eol=lf
+
+# These are Windows script files and should use crlf
+*.bat           text eol=crlf
+
+# Binary files should be left untouched
+*.jar           binary
+

examples/client-v2-apache-arrow/.gitignore

@@ -0,0 +1,5 @@
+# Ignore Gradle project-specific cache directory
+.gradle
+
+# Ignore Gradle build output directory
+build