Fixed clearing session when do cancel on Statement in jdbc

Author: chernser

CHANGELOG.md

@@ -29,6 +29,8 @@
 
 ### 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)` and `suppressOption(String)` to `InsertSettings`, `QuerySettings`, and `CommonSettings` to allow removing or suppressing specific settings. Suppressed settings (set to `null`) will not be sent to the server, which is useful for overriding global settings.
+
 - **[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.
 
 - **[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)
@@ -39,7 +41,7 @@
 
 ### Bug Fixes
 
-- **[jdbc-v2]** Fixed `Statement.cancel()` throwing `SESSION_IS_LOCKED` when the statement was running inside a ClickHouse session (e.g. via `clickhouse_setting_session_id`). The `KILL QUERY` request issued by `cancel()` now runs outside the session, so it no longer contends with the running query for the session lock. (https://github.com/ClickHouse/clickhouse-java/issues/2690)
+- **[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)
 

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

@@ -3,6 +3,7 @@
 import com.clickhouse.client.api.http.ClickHouseHttpProto;
 import com.clickhouse.client.api.internal.ValidationUtils;
 
+import java.util.HashMap;
 import java.util.Map;
 
 /**
@@ -83,7 +84,7 @@ public synchronized void updateSessionId(String sessionId) {
         setSessionId(sessionId);
     }
 
-    public synchronized void applyTo(Map<String, Object> requestSettings) {
+    public synchronized void applyTo(Map<? super String, Object> requestSettings) {
         putIfSet(requestSettings, ClickHouseHttpProto.QPARAM_SESSION_ID, sessionId);
         putIfSet(requestSettings, ClickHouseHttpProto.QPARAM_SESSION_CHECK,
                 sessionCheck == null ? null : (sessionCheck ? "1" : "0"));
@@ -92,7 +93,15 @@ public synchronized void applyTo(Map<String, Object> requestSettings) {
         putIfSet(requestSettings, ClickHouseHttpProto.QPARAM_SESSION_TIMEZONE, sessionTimezone);
     }
 
-    private static void putIfSet(Map<String, Object> settings, String key, String value) {
+    public static void clearSession(HashMap<String, Object> settings) {
+        settings.put(ClientConfigProperties.serverSetting(ClickHouseHttpProto.QPARAM_SESSION_ID), null);
+        settings.put(ClientConfigProperties.serverSetting(ClickHouseHttpProto.QPARAM_SESSION_TIMEOUT), null);
+        settings.put(ClientConfigProperties.serverSetting(ClickHouseHttpProto.QPARAM_SESSION_CHECK), null);
+        // Do not clean `session_timezone` setting because it is not related to session management and used to
+        // set timezone for consequent queries in some multi-user applications.
+    }
+
+    private static void putIfSet(Map<? super String, Object> settings, String key, String value) {
         if (value != null) {
             settings.put(ClientConfigProperties.serverSetting(key), value);
         }

client-v2/src/main/java/com/clickhouse/client/api/insert/InsertSettings.java

@@ -60,6 +60,26 @@ public InsertSettings setOption(String option, Object value) {
         return this;
     }
 
+    /**
+     * Removes options from the settings.
+     * @param option - configuration option name
+     */
+    public InsertSettings resetOption(String option) {
+        settings.resetOption(option);
+        return this;
+    }
+
+    /**
+     * Makes option value to null that makes agent to remove it from final collection.
+     * This is useful to override even global settings when they need to be removed.
+     * @param option - option key
+     * @return current settings instance
+     */
+    public InsertSettings suppressOption(String option) {
+        settings.suppressOption(option);
+        return this;
+    }
+
     /**
      * Get all settings as an unmodifiable map.
      *

client-v2/src/main/java/com/clickhouse/client/api/internal/CommonSettings.java

@@ -20,7 +20,7 @@ public class CommonSettings {
 
     private String operationId;
     private String logComment;
-    protected Map<String, Object> settings;
+    protected HashMap<String, Object> settings; // using hashmap to store null values
 
     public CommonSettings() {
         settings = new HashMap<>();
@@ -66,11 +66,27 @@ public CommonSettings setOption(String option, Object value) {
         return this;
     }
 
+    /**
+     * Removes option from the setting
+     * @param option - option key
+     * @return current settings instance
+     */
     public CommonSettings resetOption(String option) {
         settings.remove(option);
         return this;
     }
 
+    /**
+     * Makes option value to null that makes agent to remove it from final collection.
+     * This is useful to override even global settings when they need to be removed.
+     * @param option - option key
+     * @return current settings instance
+     */
+    public CommonSettings suppressOption(String option) {
+        settings.put(option, null);
+        return this;
+    }
+
     /**
      * Get all settings as an unmodifiable map.
      *
@@ -140,11 +156,7 @@ public CommonSettings use(Session session) {
     }
 
     public void clearSession() {
-        resetOption(ClientConfigProperties.serverSetting(ClickHouseHttpProto.QPARAM_SESSION_ID));
-        resetOption(ClientConfigProperties.serverSetting(ClickHouseHttpProto.QPARAM_SESSION_CHECK));
-        resetOption(ClientConfigProperties.serverSetting(ClickHouseHttpProto.QPARAM_SESSION_TIMEOUT));
-        // Do not clean `session_timezone` setting because it is not related to session management and used to
-        // set timezone for consequent queries in some multi-user applications.
+        Session.clearSession(settings);
     }
 
     /**

client-v2/src/main/java/com/clickhouse/client/api/query/QuerySettings.java

@@ -50,11 +50,26 @@ public QuerySettings setOption(String option, Object value) {
         return this;
     }
 
+    /**
+     * Removes options from the settings.
+     * @param option - configuration option name
+     */
     public QuerySettings resetOption(String option) {
         settings.resetOption(option);
         return this;
     }
 
+    /**
+     * Makes option value to null that makes agent to remove it from final collection.
+     * This is useful to override even global settings when they need to be removed.
+     * @param option - option key
+     * @return current settings instance
+     */
+    public QuerySettings suppressOption(String option) {
+        settings.suppressOption(option);
+        return this;
+    }
+
     /**
      * Gets a configuration option.
      *

client-v2/src/test/java/com/clickhouse/client/ClientTests.java

@@ -50,6 +50,7 @@
 import java.util.concurrent.Executors;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.function.BiConsumer;
 import java.util.function.BiFunction;
 import java.util.function.Consumer;
 import java.util.function.Supplier;
@@ -729,6 +730,24 @@ public void testInvalidAuthConfiguration() throws Exception {
                 Assert.assertTrue(e.getMessage().contains("Trust store and certificates cannot be used together"), e.getMessage()));
     }
 
+    @Test(groups = {"integration"})
+    public void testOverrideSettings() throws Exception {
+        final String clientTimezone = "America/Los_Angeles";
+        try (Client client = newClient().setSessionTimezone(clientTimezone).build()) {
+
+            final BiConsumer<QuerySettings, String> checkTzStmt = (settings, timezone) -> {
+                GenericRecord firstRecord = client.queryAll("SELECT timezone()", settings).stream().findFirst().get();
+                Assert.assertEquals(firstRecord.getString(1), timezone);
+            };
+
+            checkTzStmt.accept(new QuerySettings(), clientTimezone);
+
+            final String altTimezone = "America/New_York";
+            checkTzStmt.accept(new QuerySettings().setSessionTimezone(altTimezone), altTimezone);
+            checkTzStmt.accept(new QuerySettings().setOption(ClientConfigProperties.serverSetting("session_timezone"), null), "UTC");
+        }
+    }
+
     public boolean isVersionMatch(String versionExpression, Client client) {
         List<GenericRecord> serverVersion = client.queryAll("SELECT version()");
         return ClickHouseVersion.of(serverVersion.get(0).getString(1)).check(versionExpression);

docs/features.md

@@ -11,7 +11,7 @@ This document lists stable, user-visible behavior in `client-v2` and `jdbc-v2` t
 - Proxy support: Can send requests through configured HTTP proxies, including proxy credentials.
 - Connection and socket tuning: Exposes pool sizing, keep-alive, reuse strategy, connect/request/socket timeouts, and low-level socket options.
 - Query execution: Executes SQL asynchronously and returns streaming query responses with response metadata and metrics.
-- Query settings: Supports per-query database selection, output format, execution limits, roles, log comments, headers, reusable `Session` objects, session settings, server settings, and network timeout overrides.
+- Query settings: Supports per-query database selection, output format, execution limits, roles, log comments, headers, reusable `Session` objects, session settings, server settings, and network timeout overrides. Settings explicitly set to `null` are suppressed and will not be sent to the server.
 - Parameterized SQL: Accepts named query parameters and can send them through supported HTTP request encodings.
 - Result materialization helpers: Provides streaming `Records`, generic row access, and convenience APIs that materialize all rows into generic records or typed POJOs.
 - Binary format readers: Reads ClickHouse binary result formats including `Native`, `RowBinary`, `RowBinaryWithNames`, and `RowBinaryWithNamesAndTypes`.

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

@@ -1,6 +1,7 @@
 package com.clickhouse.jdbc;
 
 import com.clickhouse.client.api.ClientConfigProperties;
+import com.clickhouse.client.api.Session;
 import com.clickhouse.client.api.internal.ServerSettings;
 import com.clickhouse.client.api.query.GenericRecord;
 import com.clickhouse.data.ClickHouseVersion;
@@ -758,7 +759,11 @@ public void testCancelQueryWithSession() throws Exception {
         // "Session is locked by a concurrent client" (SESSION_IS_LOCKED). The KILL QUERY request issued by
         // cancel() must not carry the session id of the query being cancelled.
         String sessionId = "test-session-" + UUID.randomUUID();
-        try (Connection conn = getJdbcConnection()) {
+        Properties properties = new Properties();
+        Session session = new Session();
+        session.setSessionId(sessionId);
+        session.applyTo(properties);
+        try (Connection conn = getJdbcConnection(properties)) {
             try (StatementImpl stmt = (StatementImpl) conn.createStatement()) {
                 stmt.getLocalSettings().setSessionId(sessionId);
                 stmt.setQueryTimeout(30); // safety net so a failed cancel cannot hang the test
@@ -799,7 +804,12 @@ public void testCancelInsertWithSession() throws Exception {
         // Regression test for #2690 covering a long-running INSERT executed inside a session.
         String tableName = getDatabase() + ".cancel_insert_with_session";
         String sessionId = "test-session-" + UUID.randomUUID();
-        try (Connection conn = getJdbcConnection(Map.of(ASYNC_INSERT_SETTING_KEY, ServerSettings.OFF))) {
+        Properties properties = new Properties();
+        properties.put(ASYNC_INSERT_SETTING_KEY, ServerSettings.OFF);
+        Session session = new Session();
+        session.setSessionId(sessionId);
+        session.applyTo(properties);
+        try (Connection conn = getJdbcConnection(properties)) {
             try (Statement setup = conn.createStatement()) {
                 setup.execute("DROP TABLE IF EXISTS " + tableName);
                 setup.execute("CREATE TABLE " + tableName + " (num UInt64) ENGINE = MergeTree ORDER BY ()");