Integration Spec

[chernser]

Summary

• Describes ways to integrate Client or JDBC
• References examples and other materials

Checklist

Delete items not relevant to your PR:

• Closes #
• Unit and integration tests covering the common scenarios were added
• A human-readable description of the changes was provided to include in CHANGELOG
• For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

[github-actions]

Repository collaborators can run the JMH benchmark suite against this PR by commenting:

/benchmark

Optional regression threshold override (Δ% on Time or Alloc/op; defaults to 10%):

/benchmark threshold=15

Only one benchmark run per PR is active at a time — issuing a new /benchmark comment cancels the previous run. After the run finishes a separate comment will be posted comparing it against the latest scheduled run on main; the PR check fails if any benchmark regresses by more than the threshold.

[mshustov]

for partners, I'd consider adding recommended "acceptance criteria" as a separate document (can be done in a follow-up)
my braindump:

• validate functional correctness: number of rows = intended, data type conversion in a roundtrip, handles schema behaviour gracefully (type mismatch, missing column, extra column, etc)
• failure path: idempotent insert, handles retryable (network) and non-retryable errors, handles failures for long operations (1h+)
• no memory leaks under "long process" or bursty workload
• test against their own latency vs thoroughput vs parts count criteria
• operational readiness: configures client_name, can enable logging
• cloud readiness: handles idle instances, long query (1h+) failures, etc
• has auto tests against supported CH versions

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d7eab37. Configure here.}