[polyglotAI-bot]

Summary

Backports #3213 from main to v0.11.0, as @chernser requested in #3232:

@polyglotAI-bot I'm a maintainer and asking you do the PR to v0.11.0 for me I'll review myself

Issue: #3232. A closing keyword has no effect on a PR into a non-default branch, so close the issue manually after the merge.

Cherry-picked PR

PR	Merge commit on main	Backport commit
#3213	7f2cb5787	24bd9ee11 (1 conflict, in a test)

Command: git cherry-pick -x -m 1 7f2cb5787. The commit keeps its original author and records its source commit.

Conflict

There is one conflict, in executeQueryAndVerifyUserAgent in jdbc-v2/src/test/java/com/clickhouse/jdbc/ConnectionTest.java. On main, #3187 changed this helper to a retry loop before #3213 merged. #3187 is not on v0.11.0. #3213 makes two changes to the helper: the return type changes from void to String, and the helper returns userAgent.

Resolution (the same as in #3232 (comment)):

• Keep the v0.11.0 body of the helper.
• Add return userAgent; as the last statement of its try block.
• Take the rest of [client-v2] Send the User-Agent in the standard client format and add client metadata #3213 without changes: the new testClientMetadataInUserAgent test, its data provider, and the Versions import.

Diff check

26 files, +982/−97. These are the same counts as #3213 on main, and the file list and file status (added, modified, deleted) are the same.

• In 25 files, the added and removed lines are identical to [client-v2] Send the User-Agent in the standard client format and add client metadata #3213.
• In ConnectionTest.java, the added lines are also identical, but return userAgent; has one more indent level, because it is in the try block of the v0.11.0 helper.

The branch has no other changes.

Note: history/latest/3202.md (the release-note fragment of #3213) creates history/latest/ on this branch, because v0.11.0 does not have that directory. #3234 does the same with history/latest/3203.md. I kept the file as is, because the request is cherry-pick only. If the branch needs a different release-note layout, move the entry to history/0_11_0_release/CHANGELOG.md.

Test

Done in a devbox (JDK 17 + JDK 8 toolchain, Maven 3.9.15, ClickHouse server 26.9.1):

• mvn -B -DskipTests -Dmaven.javadoc.skip=true install (all 9 modules, including packages/clickhouse-jdbc-all): BUILD SUCCESS. The test sources also compile.
• client-v2 unit tests (mvn -pl client-v2 test): 796 run, 0 failures. This includes the 140 tests in the classes that [client-v2] Send the User-Agent in the standard client format and add client metadata #3213 adds or changes (UserAgentUnitTest, VersionsTest, WorkloadIdentitySupportTest, ClientUtilsTest, ClientConfigPropertiesTest, HttpAPIClientHelperTest, InsertExceptionClassificationTest).
• client-v2 HttpTransportTests#testUserAgentHasCompleteProductName+testClientName+testClientNameThruRawOptions (integration): 11 run, 0 failures.
• jdbc-v2 ConnectionTest (integration, the class with the conflict): 62 run, 59 pass, 1 skipped, 2 failures. All of testClientMetadataInUserAgent, setAndGetClientInfoTest and influenceUserAgentClientNameTest pass. The 2 failures are testSecureConnection and testSSLModeVerifyCa. They also fail on origin/v0.11.0 with no changes. They use the self-signed certificate for localhost, and the server in this environment has a different host name.

CI

CI on this PR is expected to fail before compilation starts, for a cause that is not in this PR. The CI runners use Maven 3.10.0, and on v0.11.0, packages/clickhouse-jdbc-all/pom.xml declares maven-jar-plugin two times. Details and the options are in #3233 (comment). When v0.11.0 has the fix, I merge v0.11.0 into this branch.

This PR adds no tests, docs, CHANGELOG entry or version bump other than those in #3213.

Checklist

• Issue linked: [0.11.0] Fix user agent #3232
• Only the changes of [client-v2] Send the User-Agent in the standard client format and add client metadata #3213; the one conflict is resolved as described above

🤖 Generated with Claude Code

---

Note

Medium Risk
Every HTTP request’s User-Agent string changes format, so anything parsing http_user_agent in system.query_log must be updated; misconfigured metadata fails at client build time.

Overview
Backport of #3213 to v0.11.0: HTTP User-Agent is now built in the standard ClickHouse client shape and can carry optional workload metadata.

The client composes headers as <app> clickhouse-java-v2/<version> (key:value; …; lv:java/…; os:…; hc:ahc_…) instead of the older (OS; jvm:…) plus trailing Apache-HttpClient/…. WorkloadIdentitySupport owns composition and caching; HttpAPIClientHelper delegates to it. Client.Builder#setClientName(String, Map) and the client_id_metadata config add validated key/value pairs to the comment group (with lv, os, hc filled in when not overridden). Client version and Apache HttpClient version come from a build-generated Versions class (templating-maven-plugin + java-templates), replacing filtered client-v2-version.properties.

Docs, changelog, JDBC integration tests for metadata, and broad unit/integration coverage are included. The only merge tweak is ConnectionTest#executeQueryAndVerifyUserAgent returning the captured user agent on v0.11.0.

^{Reviewed by Cursor Bugbot for commit ef48cc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chernser]

@polyglotAI-bot sync from v0.11.0 - there is fix for build

[chernser]

sync with v0.11.0 to fix the CI build

[chernser]

https://github.com/ClickHouse/clickhouse-java/blob/v0.11.0/history/0_11_0_release/CHANGELOG.md

[polyglotAI-bot]

@chernser Done. I merged v0.11.0 (fd98bda, #3236) into this branch: merge commit c1e39a8. There were no conflicts and no force-push.

• The merge adds only the two build fixes from [v0.11.0] Fix duplicate POM declarations rejected by Maven 3.10 #3236 (packages/clickhouse-jdbc-all/pom.xml, examples/client-v2/pom.xml).
• The PR diff against v0.11.0 did not change: 26 files, +982/−97, the same as [client-v2] Send the User-Agent in the standard client format and add client metadata #3213.
• Local check: mvn -DskipTests install on the full reactor (including clickhouse-jdbc-all) passes with Maven 3.9.15. CI will run the Maven 3.10 check.

[github-actions]

Triage

Category: feature • Risk: high

Summary
Backport of #3213 from main to the v0.11.0 release branch, explicitly requested by maintainer @chernser in issue #3232 ("use patch or cherry pick — no rewrites"). The change rewrites how client-v2 composes the HTTP User-Agent header: composition moves from HttpAPIClientHelper into a new WorkloadIdentitySupport class, the format changes to the standard ClickHouse client shape (<app> clickhouse-java-v2/<ver> (key:value; …; lv:…; os:…; hc:ahc_…)), a new public Client.Builder#setClientName(String, Map) API and client_id_metadata config property add validated metadata key/value pairs, and build-time versions come from a generated Versions class (new templating-maven-plugin wiring) replacing client-v2-version.properties. 26 files, +982/−97, mostly in client-v2 plus one jdbc-v2 test, docs, and a release-note fragment. One cherry-pick conflict (a jdbc-v2 test helper) was manually resolved; the author documents the resolution and an otherwise-identical diff vs. #3213.

What this impacts

• client-v2 User-Agent composition for every HTTP request (Client, HttpAPIClientHelper, new WorkloadIdentitySupport)
• Public API surface: new setClientName(String, Map) builder overload, new client_id_metadata config property, updateClientName behavior
• client-v2 build: new templating-maven-plugin, generated Versions class, removed client-v2-version.properties
• Observable behavior: the system.query_log.http_user_agent value changes format — anything parsing it must adapt
• Docs, release notes, unit/integration tests; jdbc-v2/ConnectionTest (conflict site)

Concerns

• Large diff rule fires: +982/−97 across 26 files (>400 LOC). Mitigated by being a documented cherry-pick of already-merged [client-v2] Send the User-Agent in the standard client format and add client metadata #3213, but the conflict resolution in ConnectionTest.java and overall diff identity need human verification.
• User-Agent format change ships on a patch-line release branch (v0.11.0) with no feature flag — consumers parsing http_user_agent break silently on a point release; this is a wire-observable behavior change.
• New public API surface (setClientName(String, Map), client_id_metadata) added to a release branch, widening the v0.11.x compatibility contract.
• volatile fields + synchronized update in WorkloadIdentitySupport warrant a quick concurrency sanity check (write-ordering comment suggests it was considered).
• CI is expected to fail before compilation for a pre-existing v0.11.0 build issue (duplicate maven-jar-plugin in packages/clickhouse-jdbc-all/pom.xml, see [v0.11.0] Version upgrades (backport #3183, #3184, #3182, #3196, #3195, #3223) #3233) — not caused by this PR; do not merge until the branch is fixed and re-merged here.
• Bot-authored PR (polyglotAI-bot); maintainer stated he will review it himself.

Required reviewer action

• At least one human reviewer (maintainer @chernser already volunteered); verify the conflict resolution and that the diff matches [client-v2] Send the User-Agent in the standard client format and add client metadata #3213 exactly before merging.

[chernser]

Update https://github.com/ClickHouse/clickhouse-java/blob/v0.11.0/history/0_11_0_release/CHANGELOG.md

[polyglotAI-bot]

@chernser Done in ef48cc2.

• The User-Agent entry ([client-v2] Build the User-Agent in the standard client format and let applications add metadata #3202) is now in the Breaking changes section of history/0_11_0_release/CHANGELOG.md. The text is the same as on main, without the "Breaking change:" prefix, because the section heading already says it.
• history/latest/3202.md is removed, because v0.11.0 has no history/latest/. This is the same as in [v0.11.0] Do not fail closing a partly read response that the server ended early (backport #3217) #3234.
• The commit changes only these two files. [v0.11.0] Do not fail closing a partly read response that the server ended early (backport #3217) #3234 adds its entry to Bug Fixes, so the two PRs do not conflict in the changelog.