Merge pull request #2838 from ClickHouse/04/21/26/add_jdbc_cluster_name

Added cluster name property to JDBC

Author: chernser

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## 0.9.9
 
+### 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)

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");

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

jdbc-v2/src/main/java/com/clickhouse/jdbc/ConnectionImpl.java

@@ -52,8 +52,8 @@ public class ConnectionImpl implements Connection, JdbcV2Wrapper {
     protected final JdbcConfiguration config;
 
     private boolean closed = false;
-    protected boolean onCluster;//TODO: Placeholder for cluster support
-    protected String cluster;
+    protected final boolean onCluster;
+    protected final String cluster;
     private String catalog;
     private String schema;
     private String appName;
@@ -74,8 +74,9 @@ public ConnectionImpl(String url, Properties info) throws SQLException {
         try {
             this.url = url;//Raw URL
             this.config = new JdbcConfiguration(url, info);
-            this.onCluster = false;
-            this.cluster = null;
+            final String tmpClusterName = config.getDriverProperty(DriverProperties.CLUSTER_NAME.getKey(), DriverProperties.CLUSTER_NAME.getDefaultValue());
+            this.cluster = tmpClusterName == null ? null : tmpClusterName.trim();
+            this.onCluster = this.cluster != null && !this.cluster.isEmpty();
             this.appName = "";
             this.readOnly = false;
             this.holdability = ResultSet.HOLD_CURSORS_OVER_COMMIT;

jdbc-v2/src/main/java/com/clickhouse/jdbc/DriverProperties.java

@@ -124,6 +124,11 @@ public enum DriverProperties {
     @Deprecated
     HTTP_CONNECTION_PROVIDER("http_connection_provider", null),
 
+    /**
+     * Define cluster name for statement executions like KILL
+     */
+    CLUSTER_NAME("jdbc_cluster_name", null),
+
     ;
 
 

jdbc-v2/src/main/java/com/clickhouse/jdbc/StatementImpl.java

@@ -334,7 +334,7 @@ public void cancel() throws SQLException {
         }
 
         try (QueryResponse response = connection.getClient().query(String.format("KILL QUERY%sWHERE query_id = '%s'",
-                connection.onCluster ? " ON CLUSTER " + connection.cluster + " " : " ",
+                connection.onCluster ? " ON CLUSTER " + SQLUtils.enquoteIdentifier(connection.cluster, true) + ' ' : ' ',
                 lastQueryId), connection.getDefaultQuerySettings()).get()){
             LOG.debug("Query {} was killed by {}", lastQueryId, response.getQueryId());
         } catch (Exception e) {

jdbc-v2/src/test/java/com/clickhouse/jdbc/StatementTest.java

@@ -9,6 +9,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.testng.Assert;
+import org.testng.SkipException;
 import org.testng.annotations.DataProvider;
 import org.testng.annotations.Test;
 
@@ -579,6 +580,33 @@ public void testConnectionExhaustion() throws Exception {
         }
     }
 
+    @Test(groups = {"integration"})
+    public void testCancelOnCluster() throws Exception {
+        // Generate non-existing cluster name to cause error
+        String testCluster = "test_cluster_" + RandomStringUtils.randomAlphanumeric(10);
+        Properties p = new Properties();
+        p.setProperty(DriverProperties.CLUSTER_NAME.getKey(), testCluster);
+        try (Connection conn = getJdbcConnection(p)) {
+            try (StatementImpl stmt = (StatementImpl) conn.createStatement();
+                    ResultSet rs = stmt.executeQuery("SELECT 1")) { // to fill queryId
+                try {
+                    stmt.cancel();
+                    fail("Should have thrown an exception for missing cluster");
+                } catch (SQLException e) {
+                    assertTrue(e.getMessage().contains(testCluster), "Exception should mention the missing cluster");
+                }
+            }
+        }
+
+        // no cluster set - check no exception. actual cancelation is tested elsewhere
+        try (Connection conn = getJdbcConnection()) {
+            try (StatementImpl stmt = (StatementImpl) conn.createStatement();
+                 ResultSet rs = stmt.executeQuery("SELECT 1")) { // to fill queryId
+                stmt.cancel();
+            }
+        }
+    }
+
     @Test(groups = {"integration"})
     public void testConcurrentCancel() throws Exception {
         int maxNumConnections = 3;