[integration spec] Update docs/integration-index.md - #3102
Open
chernser wants to merge 2 commits into
Open
Conversation
mshustov
approved these changes
Sep 8, 2026
| ### Releases | ||
|
|
||
| We are trying to follow [semantic versioning](https://semver.org/). Here we need to differentiate versions before `1.0.0` and after: | ||
| - In a version like `0.y.z`, `y` is incremented for significant or breaking changes. `z` is incremented when the code is patched for a few bugs, or the change is minor, like adding a new format enum constant. |
Member
There was a problem hiding this comment.
nit: not sure it's needed. the next paragraph (Before 1.0.0...) + a reference to SemVer cover this point well for anyone who is familiar with SemVer
| Why is it so important? | ||
| - Fix security issues, if any. | ||
| - Support your users with new features. | ||
| - Adopt new database behavior so your users can work with the latest ClickHouse version. |
Member
There was a problem hiding this comment.
nit: this should be the very first item: new data types, new functionality (like JWT), proven compatibility with the actively maintained CH versions, etc
| When the version lag is significant, it is almost impossible to upgrade quickly to the latest version. In the case of an emergency fix, it multiplies the problems. | ||
| It is fine to skip a few patch versions if there is an established upgrade process every few months. However, skipping a single minor version (the middle digit, where significant changes happen) will cause problems. They are usually found only after something is broken. | ||
|
|
||
| Minor versions may have many changes, and some of them need a preview from your side. In this case, we release an `-rc` version and let you know. This version is **only** for preview and not for production use. The preview lasts for a few weeks to let everyone send their feedback. If changes are needed, we will release a new `-rc` and repeat the cycle. |
Member
There was a problem hiding this comment.
send their feedback.
Where and how? Do we provide this information anywhere?
| - Adopt new database behavior so your users can work with the latest ClickHouse version. | ||
| - Fix critical issues that block normal work. | ||
|
|
||
| When the version lag is significant, it is almost impossible to upgrade quickly to the latest version. In the case of an emergency fix, it multiplies the problems. |
Member
There was a problem hiding this comment.
Should we link a migration guide? Or it does it cover the v1 -> v2 migration only?
| - Want a single, standard API across several databases and accept trading some ClickHouse-specific power for that uniformity. | ||
| - Mainly need unified access to database metadata (`DatabaseMetaData`) and straightforward row-by-row data preview rather than high-throughput streaming. | ||
| - Can accept that ClickHouse-specific types still need handling in your own code. The driver maps types such as `JSON`, `Geometry`, or `Tuple` to Java objects, but your application must interpret them — for example, casting the result of `ResultSet.getObject("coords")` to the expected type, or parsing a `JSON` column that comes back as a `String`. | ||
| - **Choose the Java Client (`client-v2`) when:** Your application loads data from various wire formats, requires maximum data fetch throughput, uses typed POJOs, or needs fine-grained operational control over ClickHouse settings. |
Member
There was a problem hiding this comment.
when your app doesn't rely on any JDBC API :D
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
No unresolved comments left from https://github.com/ClickHouse/clickhouse-java/pull/2914/changes#diff-7aebad82453fb90dbfb9423402810122f9328c9fd647fcbab4941c316d4baf8d
Checklist
Delete items not relevant to your PR: