Merge branch 'main' into 06/10/26/jsonl_support

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)` 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.
+
 - **[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/Client.java

@@ -12,6 +12,7 @@
 import com.clickhouse.client.api.data_formats.internal.ProcessParser;
 import com.clickhouse.client.api.enums.Protocol;
 import com.clickhouse.client.api.enums.ProxyType;
+import com.clickhouse.client.api.enums.SSLMode;
 import com.clickhouse.client.api.http.ClickHouseHttpProto;
 import com.clickhouse.client.api.insert.InsertResponse;
 import com.clickhouse.client.api.insert.InsertSettings;
@@ -755,6 +756,34 @@ public Builder setClientKey(String path) {
             return this;
         }
 
+        /**
+         * Defines how strictly the client verifies a server identity on secure connections.
+         *
+         * <p>Supported modes:</p>
+         * <ul>
+         *     <li>{@link SSLMode#DISABLED} - SSL is not used; only meaningful with plain protocols</li>
+         *     <li>{@link SSLMode#TRUST} - encrypt, but accept any server certificate and skip
+         *     hostname verification; a configured trust store or CA certificate is ignored (a warning
+         *     is logged), while a client certificate/key is still applied for mTLS</li>
+         *     <li>{@link SSLMode#VERIFY_CA} - validate the server certificate chain, but skip
+         *     hostname verification</li>
+         *     <li>{@link SSLMode#STRICT} - full verification of the certificate chain and the
+         *     hostname (default)</li>
+         * </ul>
+         *
+         * <p>The mode applies only when a secure protocol is in use - for the HTTP transport that
+         * means an {@code https://} endpoint. Setting any mode does <b>not</b> make the client use
+         * encryption on a plain HTTP endpoint: the endpoint scheme always decides whether the
+         * connection is encrypted.</p>
+         *
+         * @param sslMode ssl mode
+         * @return same instance of the builder
+         */
+        public Builder setSSLMode(SSLMode sslMode) {
+            this.configuration.put(ClientConfigProperties.SSL_MODE.getKey(), sslMode.name());
+            return this;
+        }
+
         /**
          * Configure client to use server timezone for date/datetime columns. Default is true.
          * If this options is selected then server timezone should be set as well.
@@ -1140,6 +1169,36 @@ public Client build() {
                 throw new ClientMisconfigurationException("Trust store and certificates cannot be used together");
             }
 
+            // A trust store and a CA certificate are not rejected here: for VERIFY_CA/STRICT the trust
+            // store takes precedence and the CA certificate is ignored with a warning (see createSSLContext).
+
+            // Resolve ssl_mode case-insensitively and normalize it to the canonical enum name so that
+            // downstream parsing is consistent and an unknown value is reported as a misconfiguration
+            // here instead of failing later with a generic enum-parsing error.
+            String sslModeValue = configuration.get(ClientConfigProperties.SSL_MODE.getKey());
+            if (sslModeValue != null) {
+                SSLMode sslMode;
+                try {
+                    sslMode = SSLMode.fromValue(sslModeValue);
+                } catch (IllegalArgumentException e) {
+                    throw new ClientMisconfigurationException("Invalid value '" + sslModeValue + "' for '"
+                            + ClientConfigProperties.SSL_MODE.getKey() + "'", e);
+                }
+                configuration.put(ClientConfigProperties.SSL_MODE.getKey(), sslMode.name());
+
+                // SSLMode.DISABLED does not turn encryption off - the endpoint scheme decides that. So it
+                // contradicts a secure (https) endpoint and must be rejected here, before the client is created.
+                if (sslMode == SSLMode.DISABLED) {
+                    for (Endpoint endpoint : this.endpoints) {
+                        if ("https".equalsIgnoreCase(endpoint.getURI().getScheme())) {
+                            throw new ClientMisconfigurationException("SSL mode '" + SSLMode.DISABLED
+                                    + "' cannot be used with a secure (https) endpoint. Use '" + SSLMode.TRUST
+                                    + "' to trust all certificates or use plain HTTP.");
+                        }
+                    }
+                }
+            }
+
             // Check timezone settings
             String useTimeZoneValue = this.configuration.get(ClientConfigProperties.USE_TIMEZONE.getKey());
             String serverTimeZoneValue = this.configuration.get(ClientConfigProperties.SERVER_TIMEZONE.getKey());
@@ -1671,15 +1730,9 @@ public CompletableFuture<QueryResponse> query(String sqlQuery, Map<String, Objec
                 for (int i = 0; i <= retries; i++) {
                     ClassicHttpResponse httpResponse = null;
                     try {
-                        boolean  useMultipart = ClientConfigProperties.HTTP_SEND_PARAMS_IN_BODY.getOrDefault(requestSettings.getAllSettings());
-                        if (queryParams != null && useMultipart) {
-                            httpResponse = httpClientHelper.executeMultiPartRequest(selectedEndpoint,
-                                    requestSettings.getAllSettings(), sqlQuery);
-                        } else {
-                            httpResponse = httpClientHelper.executeRequest(selectedEndpoint,
+                        httpResponse = httpClientHelper.executeRequest(selectedEndpoint,
                                     requestSettings.getAllSettings(),
                                     sqlQuery);
-                        }
                         // Check response
                         if (httpResponse.getCode() == HttpStatus.SC_SERVICE_UNAVAILABLE) {
                             LOG.warn("Failed to get response. Server returned {}. Retrying. (Duration: {})", httpResponse.getCode(), durationSince(startTime));

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

@@ -1,6 +1,7 @@
 package com.clickhouse.client.api;
 
 import com.clickhouse.client.api.data_formats.internal.AbstractBinaryFormatReader;
+import com.clickhouse.client.api.enums.SSLMode;
 import com.clickhouse.client.api.internal.ClickHouseLZ4OutputStream;
 import com.clickhouse.data.ClickHouseDataType;
 import com.clickhouse.data.ClickHouseFormat;
@@ -115,6 +116,8 @@ public enum ClientConfigProperties {
 
     SSL_CERTIFICATE("sslcert", String.class),
 
+    SSL_MODE("ssl_mode", SSLMode.class, SSLMode.STRICT.name()),
+
     RETRY_ON_FAILURE("retry", Integer.class, "3"),
 
     INPUT_OUTPUT_FORMAT("format", ClickHouseFormat.class),

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

@@ -83,7 +83,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 +92,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(Map<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/enums/SSLMode.java

@@ -0,0 +1,65 @@
+package com.clickhouse.client.api.enums;
+
+/**
+ * Defines how strictly the client verifies a server identity when a secure protocol is used.
+ *
+ * <p>The mode affects only connections that are already using a secure transport (for example,
+ * an {@code https://} endpoint). It does <b>not</b> enable encryption for plain protocols - an
+ * {@code http://} endpoint stays unencrypted whatever the mode is.</p>
+ *
+ * <p>Modes from the least to the most strict:</p>
+ * <ul>
+ *     <li>{@link #DISABLED} - SSL is not used. Plain protocols only.</li>
+ *     <li>{@link #TRUST} - the hostname is not verified and any server certificate is accepted, which
+ *     is susceptible to MITM attacks - use that only for testing or in fully trusted environments. A
+ *     configured trust store or CA certificate has no effect in this mode and is ignored (a warning is
+ *     logged); a configured client certificate/key is still applied for mTLS.</li>
+ *     <li>{@link #VERIFY_CA} - the server certificate chain is validated against the trust material
+ *     (default JVM trust store, configured trust store, or a CA certificate), but the hostname is
+ *     not checked against the certificate.</li>
+ *     <li>{@link #STRICT} - full verification (default): certificate chain is validated and the
+ *     hostname must match the certificate.</li>
+ * </ul>
+ */
+public enum SSLMode {
+
+    /**
+     * SSL is not used. Connection is not encrypted. Doesn't work with HTTPS.
+     * Reserved for TCP where protocol doesn't define encryption.
+     */
+    DISABLED,
+
+    /**
+     * The hostname is not verified and any server certificate is accepted. A configured trust store or
+     * CA certificate has no effect in this mode and is ignored (a warning is logged). A configured
+     * client certificate/key is still applied for mTLS.
+     */
+    TRUST,
+
+    /**
+     * Server certificate chain is validated, but the hostname is not verified.
+     */
+    VERIFY_CA,
+
+    /**
+     * Full verification: certificate chain is validated and the hostname must match
+     * the certificate. Default mode for HTTPs.
+     */
+    STRICT;
+
+    /**
+     * Case-insensitive variant of {@link #valueOf(String)}.
+     *
+     * @param value mode name in any case
+     * @return matching mode
+     * @throws IllegalArgumentException when the value does not match any mode
+     */
+    public static SSLMode fromValue(String value) {
+        for (SSLMode mode : values()) {
+            if (mode.name().equalsIgnoreCase(value)) {
+                return mode;
+            }
+        }
+        throw new IllegalArgumentException("Unknown SSL mode '" + value + "'");
+    }
+}

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

@@ -60,6 +60,15 @@ 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;
+    }
+
     /**
      * Get all settings as an unmodifiable map.
      *

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

@@ -140,11 +140,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);
     }
 
     /**