[chernser]

Summary

Followup PR for comments.

https://github.com/ClickHouse/clickhouse-java/pull/2914/changes#r3594185661

Lets add step 8 in with:

    Docker setup for local clickhouse
    cloud environment - partners get credits to use
    reference to example test suites in our repo

we should make sure to highlight areas like:

    functional correctness: row count matches, data types, schema mismatch handling
    potential failure paths: idempotent inserts, retryable vs non-retryable, long operation failures
    latency vs throughput vs part count
    client_name, logging enabled
    cloud readiness: idle instance handling, long running query failures
    automated testing against the different channels in CH cloud for version support

Docker setup and cloud environment - added as "Development environment" section.
References to example test suites will be in another document. Currently we have many examples inline.

functional correctness - covered in Failure handling in Select and Insert operations
potential failure paths
- idempotent inserts - covered in "Idempotency — deduplication token"
- what is retryable - covered in failure handling section for each operation
- long operations failures

client_name - covered in "Workload identification" section

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

---

Note

Low Risk
Documentation-only changes with no runtime or API modifications.

Overview
Adds a Development Environment section to integration-index.md with Java version guidance, a one-line Docker command for local ClickHouse, and a strong recommendation to validate integrations on ClickHouse Cloud, plus links to cloud vs OSS docs.

Reframes and expands integration-jdbc.md: new preface structure, user-facing config adaptation layer (mapping service settings to driver properties with guardrails), and clearer server vs client settings (including clickhouse_setting_ / DriverProperties.serverSetting).

Operational depth for integrators: read-path notes (FINAL, select_sequential_consistency, slow-consumer timeouts); write-path RowBinary + async insert examples and wait_async_insert=1 semantics; failure handling (client network retries vs app-level retries, ClickHouse error code 33 schema mismatch with cause-chain example); Cloud idle wake-up via Connection.isValid; minor TLS/format/observability example tweaks.

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

[laeg]

few changes and suggestions please Sergey

[laeg]

Typo: s/step/steps/

I feel like the original phrasing was better for patterns: "Work through these steps in order" - more direct and sets expectations.

Suggestion:

Work through these steps in order. Each one covers a different aspect of the integration, and the "Common Pitfalls" notes flag what breaks if you skip one.

[chernser]

Good point. Fixed.

[laeg]

This is a really good addition!

One thing that could make it stronger and more concrete is an example of why decoupling matters. I think we should encourage folks to explicitly set values (even if they are the default) in the configuration as it will mean that if they have a dependency on these, it wont break on upgrades/changes

[chernser]

Thanks!
Overriding default is good when code is maintained - I'm afraid most will be set and forgotten.
Anyway will try to do more examples.

[chernser]

I've added example, please review if more is needed.

[laeg]

Good section!

Because most frameworks (Spring, Hibernate, etc.) typically wrap exceptions in their own exception type, have we verified whether the exception chain is bubbled up to the user? This might save partners some debugging time / help us if they've not exposed the full chain, so let's encourage them to recursively walk the full chain.

[chernser]

I've updated - please review - may be need more corrections