Merge branch 'main' into 04/10/26/json_format_support

Author: chernser

.cursor/skills/update-keyword-engine-lists/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: update-keyword-engine-lists
+description: Update ALLOWED_KEYWORD_ALIASES in ClickHouseSqlUtils.java and ENGINE_TO_TABLE_TYPE in DatabaseMetaDataImpl.java from failing test output. Use when StatementSQLTest.testAllowedKeywordAliasesMatchSystemKeywords or DatabaseMetaDataTest.testAllTableEnginesFromSystemTableEnginesAreMapped fails.
+---
+
+# Update keyword and engine lists from test failures
+
+## Files
+
+**Keywords:**
+`jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/parser/javacc/ClickHouseSqlUtils.java`
+— `initAllowedKeywordAliases()`, append after the last `// Appended` comment block.
+
+**Engines:**
+`jdbc-v2/src/main/java/com/clickhouse/jdbc/metadata/DatabaseMetaDataImpl.java`
+— `ENGINE_TO_TABLE_TYPE` static block, insert a new group before `// Special`.
+
+## Steps
+
+1. Parse the failing test message to extract the list of missing items.
+
+2. **For keywords** (`StatementSQLTest` failure — e.g. `["CURSOR", "DETERMINISTIC", ...]`):
+   Append a new dated comment + entries at the end of `buildKeywordSet(...)`, after the last existing `// Appended` block:
+   ```java
+   // Appended MM/DD/YYYY
+   "KEYWORD1", "KEYWORD2", ...
+   ```
+   The previous entry must have a trailing comma. Keep alphabetical order within the new block.
+
+3. **For engines** (`DatabaseMetaDataTest` failure — e.g. `[Paimon, PaimonAzure, ...]`):
+   Add a new named group before `// Special` in the static block:
+   ```java
+   // <GroupName> (appended MM/DD/YYYY)
+   map.put("Engine1", TableType.REMOTE_TABLE.getTypeName());
+   ```
+   Choose `TableType` by analogy:
+   - External storage (S3/Azure/HDFS variants, lake formats) → `REMOTE_TABLE`
+   - MergeTree family or local engines → `TABLE`
+
+## Output
+
+After editing, output this git commit command:
+
+```
+git commit -m "jdbc-v2: update <keywords|engines|keywords and engines> in JDBC"
+```

CHANGELOG.md

@@ -17,8 +17,20 @@
 
   (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]** 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.
+
+- **[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 <token>")`), or use `useBearerTokenAuth(String)` which prepends `Bearer ` automatically.
+
+- **[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.
+
 ### New Features
 
+- **[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)
 
 - **[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/src/main/java/com/clickhouse/client/api/Client.java

@@ -16,6 +16,7 @@
 import com.clickhouse.client.api.insert.InsertResponse;
 import com.clickhouse.client.api.insert.InsertSettings;
 import com.clickhouse.client.api.internal.ClientStatisticsHolder;
+import com.clickhouse.client.api.internal.CredentialsManager;
 import com.clickhouse.client.api.internal.HttpAPIClientHelper;
 import com.clickhouse.client.api.internal.MapUtils;
 import com.clickhouse.client.api.internal.TableSchemaParser;
@@ -44,7 +45,6 @@
 import org.apache.hc.core5.concurrent.DefaultThreadFactory;
 import org.apache.hc.core5.http.ClassicHttpResponse;
 import org.apache.hc.core5.http.Header;
-import org.apache.hc.core5.http.HttpHeaders;
 import org.apache.hc.core5.http.HttpStatus;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -105,7 +105,8 @@
  *
  *
  *
- * <p>Client is thread-safe. It uses exclusive set of object to perform an operation.</p>
+ * <p>Client is thread-safe. It uses exclusive set of object to perform an operation.
+ * Exception is client global authentication configuration. Application should handle it in the way it is designed.</p>
  *
  */
 public class Client implements AutoCloseable {
@@ -140,11 +141,13 @@ public class Client implements AutoCloseable {
     private final int retries;
     private LZ4Factory lz4Factory = null;
     private final Supplier<String> queryIdGenerator;
+    private final CredentialsManager credentialsManager;
 
     private Client(Collection<Endpoint> endpoints, Map<String,String> configuration,
                    ExecutorService sharedOperationExecutor, ColumnToMethodMatchingStrategy columnToMethodMatchingStrategy,
-                   Object metricsRegistry, Supplier<String> queryIdGenerator) {
-        Map<String, Object> parsedConfiguration = ClientConfigProperties.parseConfigMap(configuration);
+                   Object metricsRegistry, Supplier<String> queryIdGenerator, CredentialsManager cManager) {
+        Map<String, Object> parsedConfiguration = new ConcurrentHashMap<>(ClientConfigProperties.parseConfigMap(configuration));
+        this.credentialsManager = cManager;
         this.session = Session.extractFrom(parsedConfiguration);
         this.configuration = new ConcurrentHashMap<>(parsedConfiguration);
         this.readOnlyConfig = Collections.unmodifiableMap(configuration);
@@ -1039,12 +1042,13 @@ public Builder setOptions(Map<String, String> options) {
          * Specifies whether to use Bearer Authentication and what token to use.
          * The token will be sent as is, so it should be encoded before passing to this method.
          *
-         * @param bearerToken - token to use
+         * @param bearerToken - token to use (without {@code Bearer} prefix)
          * @return same instance of the builder
          */
         public Builder useBearerTokenAuth(String bearerToken) {
             // Most JWT libraries (https://jwt.io/libraries?language=Java) compact tokens in proper way
-            this.httpHeader(HttpHeaders.AUTHORIZATION, "Bearer " + bearerToken);
+            // Bearer token in subset of access token
+            setAccessToken(CredentialsManager.AUTH_HEADER_BEARER_PREFIX + bearerToken);
             return this;
         }
 
@@ -1128,28 +1132,12 @@ public Client build() {
             if (this.endpoints.isEmpty()) {
                 throw new IllegalArgumentException("At least one endpoint is required");
             }
-            // check if username and password are empty. so can not initiate client?
-            boolean useSslAuth = MapUtils.getFlag(this.configuration, ClientConfigProperties.SSL_AUTH.getKey());
-            boolean hasAccessToken = this.configuration.containsKey(ClientConfigProperties.ACCESS_TOKEN.getKey());
-            boolean hasUser = this.configuration.containsKey(ClientConfigProperties.USER.getKey());
-            boolean hasPassword = this.configuration.containsKey(ClientConfigProperties.PASSWORD.getKey());
-            boolean customHttpHeaders = this.configuration.containsKey(ClientConfigProperties.httpHeader(HttpHeaders.AUTHORIZATION));
-
-            if (!(useSslAuth || hasAccessToken || hasUser || hasPassword || customHttpHeaders)) {
-                throw new IllegalArgumentException("Username and password (or access token or SSL authentication or pre-define Authorization header) are required");
-            }
-
-            if (useSslAuth && (hasAccessToken || hasPassword)) {
-                throw new IllegalArgumentException("Only one of password, access token or SSL authentication can be used per client.");
-            }
 
-            if (useSslAuth && !this.configuration.containsKey(ClientConfigProperties.SSL_CERTIFICATE.getKey())) {
-                throw new IllegalArgumentException("SSL authentication requires a client certificate");
-            }
+            CredentialsManager cManager = new CredentialsManager(this.configuration);
 
-            if (this.configuration.containsKey(ClientConfigProperties.SSL_TRUST_STORE.getKey()) &&
-                this.configuration.containsKey(ClientConfigProperties.SSL_CERTIFICATE.getKey())) {
-                throw new IllegalArgumentException("Trust store and certificates cannot be used together");
+            if (configuration.containsKey(ClientConfigProperties.SSL_TRUST_STORE.getKey()) &&
+                    configuration.containsKey(ClientConfigProperties.SSL_CERTIFICATE.getKey())) {
+                throw new ClientMisconfigurationException("Trust store and certificates cannot be used together");
             }
 
             // Check timezone settings
@@ -1181,7 +1169,7 @@ public Client build() {
             }
 
             return new Client(this.endpoints, this.configuration, this.sharedOperationExecutor,
-                this.columnToMethodMatchingStrategy, this.metricRegistry, this.queryIdGenerator);
+                this.columnToMethodMatchingStrategy, this.metricRegistry, this.queryIdGenerator, cManager);
         }
     }
 
@@ -2114,7 +2102,8 @@ public String toString() {
     }
 
     /**
-     * Returns unmodifiable map of configuration options.
+     * Returns unmodifiable map of initial configuration options.
+     * As authentication configuration values can change this map doesn't reflect them.
      * @return - configuration options
      */
     public Map<String, String> getConfiguration() {
@@ -2194,8 +2183,44 @@ public Collection<String> getDBRoles() {
         return unmodifiableDbRolesView;
     }
 
+
+    /**
+     * Updates Bearer token for other requests.
+     * This method is not thread-safe with respect to other credential updates
+     * or concurrent request execution. Applications must coordinate access if
+     * they require stronger consistency.
+     * Method doesn't allow to switch authentication type
+     * @param bearer - token to use without {@code "Bearer"} prefix.
+     */
     public void updateBearerToken(String bearer) {
-        this.configuration.put(ClientConfigProperties.httpHeader(HttpHeaders.AUTHORIZATION), "Bearer " + bearer);
+        ValidationUtils.checkNonBlank(bearer, "Bearer token");
+        updateAccessToken(CredentialsManager.AUTH_HEADER_BEARER_PREFIX + bearer);
+    }
+
+    /**
+     * Updates the user and password for all subsequential requests.
+     * This method is not thread-safe with respect to other credential updates
+     * or concurrent request execution. Applications must coordinate access if
+     * they require stronger consistency.
+     * Method doesn't allow to switch authentication type
+     * @param username user name
+     * @param password user password
+     * @throws ClientMisconfigurationException if another authentication type in use.
+     */
+    public void updateUserAndPassword(String username, String password) {
+        this.credentialsManager.setCredentials(username, password);
+    }
+
+    /**
+     * Updates access token for the client. Change will be applied to all following requests.
+     * This method is not thread-safe with respect to other credential updates
+     * or concurrent request execution. Applications must coordinate access if
+     * they require stronger consistency.
+     * Method doesn't allow to switch authentication type
+     * @param accessToken - plain text access token
+     */
+    public void updateAccessToken(String accessToken) {
+        this.credentialsManager.setAccessToken(accessToken);
     }
 
     private Endpoint getNextAliveNode() {
@@ -2213,6 +2238,7 @@ private Endpoint getNextAliveNode() {
     private Map<String, Object> buildRequestSettings(Map<String, Object> opSettings) {
         Map<String, Object> requestSettings = new HashMap<>(configuration);
         session.applyTo(requestSettings);
+        credentialsManager.applyCredentials(requestSettings);
         requestSettings.putAll(opSettings);
         return requestSettings;
     }

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

@@ -0,0 +1,13 @@
+package com.clickhouse.client.api.internal;
+
+/**
+ * Class containing utility methods used across the client.
+ */
+public final class ClientUtils {
+
+    private ClientUtils() {}
+
+    public static boolean isNotBlank(String str) {
+        return str != null && !str.trim().isEmpty();
+    }
+}