[jdbc-v2] Documented driver property disable_frameworks_detection makes the connection fail: Unknown and unmapped config properties #3218

Description

disable_frameworks_detection is listed under Driver properties in the JDBC docs (docs/clickhouse-docs/jdbc.mdx:79). When an application sets it, jdbc-v2 does not create the connection. This occurs for every value (true and false) and for both the Properties form and the URL query-parameter form. The driver forwards the key to client-v2, and client-v2 rejects unknown keys.

This is a regression from 0.9.7. With released clickhouse-jdbc 0.9.6 (all), the same key gives only a WARN Unknown and unmapped config properties: {disable_frameworks_detection=true} and the connection is created. With 0.9.7 (the first release that has #2712, "Handling of unknown parameters"), and with 0.11.0-rc1 and main, the connection fails.

Related problem with the same key: with ignore_unknown_config_key=true as a workaround, the connection is created. But the URL form ?disable_frameworks_detection=true has no effect: the frameworks are still added to the User-Agent. Only the Properties form disables the detection.

Steps to reproduce

1. Connect with new com.clickhouse.jdbc.Driver().connect("jdbc:clickhouse://host:8123/default", props), where props has disable_frameworks_detection=true (or false).
2. Or connect with jdbc:clickhouse://host:8123/default?disable_frameworks_detection=true.
3. In both cases, connect throws.

Error Log or Exception StackTrace

java.sql.SQLException: Failed to create connection
	at com.clickhouse.jdbc.ConnectionImpl.<init>(ConnectionImpl.java:155)
	at com.clickhouse.jdbc.Driver.connect(Driver.java:106)
Caused by: com.clickhouse.client.api.ClientMisconfigurationException: Unknown and unmapped config properties: [disable_frameworks_detection]
	at com.clickhouse.client.api.ClientConfigProperties.parseConfigMap(ClientConfigProperties.java:446)
	at com.clickhouse.client.api.Client.<init>(Client.java:183)
	at com.clickhouse.client.api.Client$Builder.build(Client.java:1431)
	at com.clickhouse.jdbc.ConnectionImpl.<init>(ConnectionImpl.java:116)

Expected Behaviour

The docs list disable_frameworks_detection as a driver property. The driver must accept it, must not forward it to the client, and true must remove the detected frameworks from the User-Agent. The URL form and the Properties form must have the same result, as for other driver properties.

Observed results (main @ 5392b64, caller class in package org.apache.spark.repro so that detection finds apache.spark). The User-Agent values are http_user_agent from system.query_log on the server:

Released clickhouse-jdbc-0.11.0-rc1-all.jar gives the same results.

The ((apache.spark)) double parentheses are a different problem, reported in #3214.

Root cause

• jdbc-v2/src/main/java/com/clickhouse/jdbc/DriverProperties.java: the enum has no entry for disable_frameworks_detection.
• jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/JdbcConfiguration.java:386-395 (buildFinalProperties): a key that is not in DRIVER_PROP_KEYS goes into clientProperties. Thus disable_frameworks_detection is sent to Client.Builder.
• client-v2/src/main/java/com/clickhouse/client/api/ClientConfigProperties.java:440-446 (parseConfigMap): since [client-v2, jdbc-v2] Handling of unknown parameters  #2712, an unknown key causes ClientMisconfigurationException, unless ignore_unknown_config_key=true.
• JdbcConfiguration.java:124 reads the flag with props.getProperty("disable_frameworks_detection", "false") from the Properties argument only, before buildFinalProperties merges the URL parameters. Thus the URL form never sets the flag.
• Docs: docs/clickhouse-docs/jdbc.mdx:79 gives the default as true. The code default is false (detection is on when the key is not set), and the "no property" row above confirms this.

Suggested fix

1. Add a DriverProperties entry for disable_frameworks_detection (default false). buildFinalProperties then keeps it in driverProperties and does not forward it to the client.
2. Read the flag from the merged driver properties (getDriverProperty(...)) after buildFinalProperties, not from the raw info argument, so the URL form works too.
3. Change the documented default in jdbc.mdx to false.

Behavior that must not change: other unknown keys must still cause ClientMisconfigurationException (#2712), and when the key is not set, framework detection must stay on.

Code Example

Properties props = new Properties();
props.setProperty("user", "default");
props.setProperty("password", "...");
props.setProperty("disable_frameworks_detection", "true");
try (Connection c = new com.clickhouse.jdbc.Driver().connect("jdbc:clickhouse://localhost:8123/default", props)) {
    // not reached: SQLException "Failed to create connection"
}

Configuration

Client Configuration

// as above: user, password, disable_frameworks_detection

Environment

• Cloud
• Client version: jdbc-v2 main @ 5392b64 (0.12.0-rc1-SNAPSHOT); also released clickhouse-jdbc 0.11.0-rc1 and 0.9.7 (all). Released 0.9.6 does not fail.
• Language version: Java 17.0.20.1
• OS: Linux

ClickHouse Server

• ClickHouse Server version: 26.9.1.1629
• ClickHouse Server non-default settings, if any: none relevant
• CREATE TABLE statements for tables involved: none (SELECT 1 is sufficient)
• Sample data for all these tables: n/a

Found by automated analysis of the client (Polyglot AI) while working on #3214. Verified against a live server with the main build and with released jars, not by code inspection only.