Skip to content

[Integration Spec] Update docs/integration-jdbc.md - #3103

Draft
chernser wants to merge 5 commits into
mainfrom
09/06/26/int_spec_jdbc_changes
Draft

chernser wants to merge 5 commits into
mainfrom
09/06/26/int_spec_jdbc_changes

Conversation

@chernser

@chernser chernser commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

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

Comment thread docs/integration-index.md

You can also use any recent [official ClickHouse binary](https://clickhouse.com/docs/en/getting-started/install/) or use Docker Compose for more complex setups.

> **Note:** Local environments are best for initial integration, experiments, and CI pipelines — not for realistic scale, performance, or operational requirements.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do you know of any documentation that outlines the differences between cloud? might be good to link to

Comment thread docs/integration-index.md

Using ClickHouse Cloud during integration helps uncover configuration or authentication nuances, avoid brittle local-only assumptions, and validates your app against true cloud operations. All features described in this guide are supported equally, and connection examples are identical — just provide your cloud hostname, port, and TLS-enabled URL in the JDBC connection string.

> **Best practice:** Validate your integration against ClickHouse Cloud regularly, especially before feature launches and release cutoffs.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🪨 ⭐

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants