Skip to content

[Integration Spec] Update integration-client.md - #3170

Open
chernser wants to merge 16 commits into
mainfrom
09/26/26/int_spec_client_update
Open

chernser wants to merge 16 commits into
mainfrom
09/26/26/int_spec_client_update

Conversation

@chernser

@chernser chernser commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Update integration-client.md
  • Changes structure to be more consistent
  • Reorganizes sections
  • Resolves follow up comments

Previous Comments

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
Changes are documentation-only (no runtime code); risk is limited to possible doc inaccuracies or broken links.

Overview
This PR expands and restructures the Java integration documentation across integration-client.md, integration-jdbc.md, integration-index.md, integration-ops.md, and clickhouse-docs/client.mdx, with integration-client.md as the main focus (structure, section order, and follow-up comment fixes).

clickhouse-docs/client.mdx adds a ClickHouse ↔ Java type mapping table (with reader/writer notes for binary formats) and a new Optimization / compression section (native block vs HTTP vs app-precompressed payloads, plus configuration property reference).

integration-client.md is reorganized for consistency: configuration references with Client.Builder / runtime / per-operation examples, richer Step 1 (client capabilities and lifecycle), default database, connection pool guidance (Cloud vs bursty vs batch patterns), retry policy and ServerException.isRetriable(), data types pointers, an Optimization chapter (compression examples, pool, JVM/GC), and updated official doc URLs.

integration-jdbc.md gets a new preface, server/client settings examples, read features (FINAL, sequential consistency), async RowBinary ingest guidance, failure handling (retries, schema mismatch / error 33), and link updates to published docs.

integration-index.md adds development environment guidance (Java versions, local Docker, ClickHouse Cloud) and fixes client doc links.

Reviewed by Cursor Bugbot for commit b30fdcf. Bugbot is set up for automated code reviews on this repo. Configure here.

@chernser
chernser requested a review from mzitnik as a code owner September 30, 2026 06:19
@chernser chernser changed the title Update integration-client.md [Integration Spec] Update integration-client.md Sep 30, 2026

@laeg laeg left a comment

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.

some changes that would be great to address please mate!

Comment thread docs/integration-client.md Resolved
Comment thread docs/integration-client.md Outdated
| `connection_pool_enabled` (`.enableConnectionPool()`) | Enable/disable HTTP connection pooling (keep enabled). | `true` |
| Property | Builder method | Purpose |
|-------------------------------|-------------------------------------|-------------------------------------------------------------------------------------------|
| `max_open_connections` | `.setMaxConnections()` | Maximum open HTTP connections per server endpoint. Size set from parallelism guidance above.|

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.

I liked that we had the defaults included previously and a recommendation

Also thinking about the type of folks grabbing this, I think we should include back in a baseline example that folks can copy and paste:

public Client.Builder createBaseClient() {
    return new Client.Builder()
        .addEndpoint("https://your-host:8443")
        .setUsername("default")
        .setPassword("secret")
        .setMaxConnections(50)
        .setConnectionRequestTimeout(5, TimeUnit.SECONDS)
        .setKeepAliveTimeout(60, TimeUnit.SECONDS)
        .setConnectionReuseStrategy(ConnectionReuseStrategy.FIFO);
}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Returned. This example might be a bit harmful because it sets some extra besides we have other examples further. But I have added a baseline example anyway

Comment thread docs/integration-client.md Resolved
Comment thread docs/integration-client.md Resolved
Comment thread docs/integration-client.md Resolved
@chernser
chernser requested a review from laeg November 5, 2026 23:17
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