Merge pull request #2829 from ClickHouse/04/16/26/jdbc_override_settings

[jdbc-v2] Fixed overriding server settings in JDBC Connection

Author: chernser

CHANGELOG.md

@@ -1,5 +1,22 @@
 ## 0.10.9
 
+### Breaking Changes
+
+- **[jdbc-v2]** The driver no longer hardcodes the server settings `async_insert=0` and `wait_end_of_query=0` on every JDBC
+  connection. This unblocks two scenarios that previously did not work: overriding these settings per connection or per
+  statement, and using the driver against read-only profiles that disallow `SETTINGS` overrides. There are two consequences:
+  - The driver now follows the server-side defaults for these settings (note: starting with ClickHouse 26.3, `async_insert`
+    defaults to `1`). Removing the explicit `wait_end_of_query=0` is a no-op against server defaults but lets users opt in to
+    `wait_end_of_query=1`.
+  - The row count returned by `java.sql.Statement.executeUpdate(java.lang.String)` (and the matching `PreparedStatement`
+    method) is no longer guaranteed to be accurate for INSERT statements when the server runs them asynchronously, and
+    parsing/data errors in the INSERT body may not surface synchronously as a `SQLException`. Previously these were
+    accurate because inserts were forced to be synchronous (see also https://github.com/ClickHouse/ClickHouse/issues/57768).
+    To restore the previous behavior, set `async_insert=0` (or `wait_for_async_insert=1`) per connection or statement.
+    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)

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

@@ -46,4 +46,9 @@ public final class ServerSettings {
     public static final String ASYNC_INSERT = "async_insert";
 
     public static final String WAIT_ASYNC_INSERT = "wait_for_async_insert";
+
+    // Misc
+    public static final String ON = "1";
+
+    public static final String OFF = "0";
 }

docs/features.md

@@ -82,3 +82,4 @@ Compatibility-sensitive traits:
 - `getString()` formatting for temporal values is stable output: `Date` uses `yyyy-MM-dd`, `DateTime` uses `yyyy-MM-dd HH:mm:ss`, and `DateTime64` preserves fractional precision, all interpreted in server timezone context where applicable.
 - Date and timestamp setters with `Calendar` are timezone-sensitive by design. Preserving the current day-shift and instant-preserving behavior is important for compatibility.
 - `setObject()` temporal behavior is specific and should not drift: `LocalDateTime` and `Instant` are rendered through `fromUnixTimestamp64Nano(...)`, while `Timestamp` and `Date` use quoted textual forms.
+- INSERT result semantics depend on server-side `async_insert` and `wait_for_async_insert`. The driver does not override these settings, so it follows whatever the server profile or user configuration sets. When `async_insert=1` and `wait_for_async_insert=0`, `Statement.executeUpdate(...)` and `PreparedStatement.executeUpdate(...)` may return `0` (or an under-counted value), and parsing/data errors in the INSERT body may not be reported synchronously as a `SQLException`. Set `async_insert=0` (or `wait_for_async_insert=1`) per connection or statement to restore synchronous row counts and error reporting.

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

@@ -2,7 +2,6 @@
 
 import com.clickhouse.client.api.Client;
 import com.clickhouse.client.api.ClientConfigProperties;
-import com.clickhouse.client.api.internal.ServerSettings;
 import com.clickhouse.client.api.metadata.TableSchema;
 import com.clickhouse.client.api.query.GenericRecord;
 import com.clickhouse.client.api.query.QuerySettings;
@@ -111,9 +110,7 @@ public ConnectionImpl(String url, Properties info) throws SQLException {
                 this.client.loadServerInfo();
             }
             this.schema = client.getDefaultDatabase();
-            this.defaultQuerySettings = new QuerySettings()
-                    .serverSetting(ServerSettings.ASYNC_INSERT, "0")
-                    .serverSetting(ServerSettings.WAIT_END_OF_QUERY, "0");
+            this.defaultQuerySettings = new QuerySettings();
 
             this.metadata = new DatabaseMetaDataImpl(this, false, url);
             this.defaultCalendar = Calendar.getInstance();

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/JdbcConfiguration.java

@@ -74,7 +74,7 @@ public boolean isIgnoreUnsupportedRequests() {
 
     /**
      * Parses URL to get property and target host.
-     * Properties that are passed in the {@code info} parameter will override that are set in the {@code url}.
+     * Properties that are passed in the {@code url} will override the {@code info} ones.
      * @param url - JDBC url
      * @param info - Driver and Client properties.
      */
@@ -89,7 +89,7 @@ public JdbcConfiguration(String url, Properties info) throws SQLException {
 
         Map<String, String> urlProperties = parseUrl(url);
         String tmpConnectionUrl = urlProperties.remove(PARSE_URL_CONN_URL_PROP);
-        initProperties(urlProperties, props);
+        buildFinalProperties(urlProperties, props);
 
         // after initializing all properties - set final connection URL
         boolean useSSLInfo = Boolean.parseBoolean(props.getProperty(DriverProperties.SECURE_CONNECTION.getKey(), "false"));
@@ -266,7 +266,12 @@ private Map<String, String> parseUrl(String url) throws SQLException {
         return properties;
     }
 
-    private void initProperties(Map<String, String> urlProperties, Properties providedProperties) {
+    /**
+     * Combines url properties and provided ones via {@link java.sql.Driver#connect(String, Properties)}
+     * @param urlProperties - properties parsed from URL
+     * @param providedProperties - properties object provided by application
+     */
+    private void buildFinalProperties(Map<String, String> urlProperties, Properties providedProperties) {
 
         // Copy provided properties
         Map<String, String> props = new HashMap<>();

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

@@ -4,20 +4,24 @@
 import com.clickhouse.client.ClickHouseProtocol;
 import com.clickhouse.client.ClickHouseServerForTest;
 import com.clickhouse.client.api.ClientConfigProperties;
-import com.clickhouse.client.api.query.GenericRecord;
+import com.clickhouse.client.api.internal.ServerSettings;
 import com.clickhouse.data.ClickHouseVersion;
 import com.clickhouse.logging.Logger;
 import com.clickhouse.logging.LoggerFactory;
 
 import java.sql.Connection;
 import java.sql.SQLException;
 import java.sql.Statement;
-import java.util.List;
+import java.util.Map;
 import java.util.Properties;
 
 public abstract class JdbcIntegrationTest extends BaseIntegrationTest {
     private static final Logger LOGGER = LoggerFactory.getLogger(JdbcIntegrationTest.class);
 
+    public static final String WAIT_ASYNC_SETTING_KEY = DriverProperties.serverSetting(ServerSettings.WAIT_ASYNC_INSERT);
+    public static final String WAIT_QUERY_SETTING_KEY = DriverProperties.serverSetting(ServerSettings.WAIT_END_OF_QUERY);
+    public static final String ASYNC_INSERT_SETTING_KEY = DriverProperties.serverSetting(ServerSettings.ASYNC_INSERT);
+
     public String getEndpointString() {
         return getEndpointString(isCloud());
     }
@@ -28,7 +32,15 @@ public String getEndpointString(boolean includeDbName) {
     }
 
     public Connection getJdbcConnection() throws SQLException {
-        return getJdbcConnection(null);
+        return getJdbcConnection((Properties) null);
+    }
+
+    public Connection getJdbcConnection(Map<String, Object> propertiesMap) throws SQLException {
+        Properties config = new Properties();
+        if (propertiesMap != null && !propertiesMap.isEmpty()) {
+            config.putAll(propertiesMap);
+        }
+        return getJdbcConnection(config);
     }
 
     public Connection getJdbcConnection(Properties properties) throws SQLException {

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

@@ -1,6 +1,7 @@
 package com.clickhouse.jdbc;
 
 import com.clickhouse.client.api.DataTypeUtils;
+import com.clickhouse.client.api.internal.ServerSettings;
 import com.clickhouse.data.ClickHouseColumn;
 import com.clickhouse.data.ClickHouseDataType;
 import com.clickhouse.data.ClickHouseVersion;
@@ -956,7 +957,7 @@ void testBatchInsertTextStatement(String sql) throws Exception {
         String table = "test_batch_text";
         long seed = System.currentTimeMillis();
         Random rnd = new Random(seed);
-        try (Connection conn = getJdbcConnection()) {
+        try (Connection conn = getJdbcConnection(Map.of(ASYNC_INSERT_SETTING_KEY, ServerSettings.OFF))) {
 
             try (Statement stmt = conn.createStatement()) {
                 stmt.execute("CREATE TABLE IF NOT EXISTS " + table +
@@ -1007,7 +1008,7 @@ void testBatchInsertNoValuesReuse() throws Exception {
         String sql = "INSERT INTO %s (v1, v2) VALUES (?, ?)";
         long seed = System.currentTimeMillis();
         Random rnd = new Random(seed);
-        try (Connection conn = getJdbcConnection()) {
+        try (Connection conn = getJdbcConnection(Map.of(ASYNC_INSERT_SETTING_KEY, ServerSettings.OFF))) {
 
             try (Statement stmt = conn.createStatement()) {
                 stmt.execute("CREATE TABLE IF NOT EXISTS " + table +
@@ -1062,7 +1063,7 @@ void testBatchInsertValuesReuse() throws Exception {
         String sql = "INSERT INTO %s (v1, v2) VALUES (1, ?)";
         long seed = System.currentTimeMillis();
         Random rnd = new Random(seed);
-        try (Connection conn = getJdbcConnection()) {
+        try (Connection conn = getJdbcConnection(Map.of(ASYNC_INSERT_SETTING_KEY, ServerSettings.OFF))) {
 
             try (Statement stmt = conn.createStatement()) {
                 stmt.execute("CREATE TABLE IF NOT EXISTS " + table +
@@ -1266,7 +1267,7 @@ public void testJdbcEscapeSyntax() throws Exception {
 
     @Test(groups = {"integration "})
     public void testStatementsWithDatabaseInTableIdentifier() throws Exception {
-        try (Connection conn = getJdbcConnection()) {
+        try (Connection conn = getJdbcConnection(Map.of(ASYNC_INSERT_SETTING_KEY, ServerSettings.OFF))) {
             final String db1Name = conn.getSchema() + "_db1";
             final String table1Name = "table1";
             try (Statement stmt = conn.createStatement()) {
@@ -1296,7 +1297,7 @@ public void testStatementsWithDatabaseInTableIdentifier() throws Exception {
 
     @Test(groups = {"integration "})
     public void testNullValues() throws Exception {
-        try (Connection conn = getJdbcConnection()) {
+        try (Connection conn = getJdbcConnection(Map.of(ASYNC_INSERT_SETTING_KEY, ServerSettings.OFF))) {
             final String table = "test_null_values";
             try (Statement stmt = conn.createStatement()) {
                 stmt.execute("DROP TABLE IF EXISTS " + table);