Semantic Versioning Approach of CrateDB
CrateDB is based on the semantic versioning approach but brings its own variation. The rationale is that semantic versioning is defined for APIs, and for a database with storage formats, a strict interpretation for semantic versioning will not be able to capture important aspects of the lifecycle of a database product.
A release of CrateDB is a triplet of integers MAJOR, MINOR, and PATCH, and these are incremented in the following way:
- MAJOR version if there are any changes to storage formats (upgrades to Lucene in particular)
- MINOR version if the release adds new functionality or introduces breaking changes (incompatible) to existing APIs
- PATCH version if there are only backward compatible bug fixes
Furthermore:
- If MAJOR is incremented, MINOR and PATCH are set to zero
- If MINOR is incremented, PATCH is set to zero
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
Details on Semantic Version Support of CrateDB
The following paragraphs outline how CrateDB handles these types of version releases in detail:
- Major versions: A major version release can contain major changes to the API and storage format of tables or table partitions. CrateDB maintains upwards storage compatibility for two releases, i.e. CrateDB 5.y.z. is compatible to CrateDB 4.y.z, but is not compatible with tables crated in CrateDB 3.y.z or earlier. These limitations do not affect table metadata and tables created with earlier versions that can be converted into the new storage format. However, this process might require manual intervention. Major versions of CrateDB typically are released every 12 to 24 months.
- Minor versions, also called "feature releases”, include a blend of new features, behind-the-scenes improvements, and changes to existing capabilities that are usually backwards compatible with previous minor versions. Minor releases also contain the patch releases of previous minor versions. Occasionally, minor releases can contain deprecations as well as breaking changes whenever necessary to minimize impact and not provide releases with a larger number of breaking changes, which typically require a larger effort to migrate to. The release notes will contain hints on any breaking changes as well as migration guidelines.
Unless stated otherwise in the release notes, rolling upgrades from a previous minor version will be possible for any minor version of the current major version and the latest minor release of the previous major version. Hotfix releases are not scheduled as our regular releases, and they should not be considered for rolling upgrades. Please refer to the release notes if downgrades to previous minor versions are possible - in case of changed table metadata, these might not be possible. - Patch versions, also called "bugfix" or "security" releases, include fixes only. These fixes could be needed to restore previous (documented) behavior, fix obvious shortcomings of new features, or offer critical fixes for security or installation issues. Rolling upgrades and downgrades are possible between patch versions within the same feature release. Patch versions are released whenever necessary and do not follow a fixed schedule.
We are committed to avoid breaking changes in minor versions for end users of CrateDB. There are types of breaking changes that may be included in minor versions:
- SQL statements and scalar functions if the change will enhance the compatibility with the SQL standard and/or PostgreSQL
- Simplification of SQL statements, scalar functions or APIs which leads to a unification across cloud providers
- Mitigation of a significant negative performance impact in a previous MAJOR version
Under rare circumstances, we can introduce a breaking change in a PATCH version when the behavior of a feature is incorrect, but the fix will lead to a breaking change.
Version Support of CrateDB
CrateDB provides different support levels for different versions, which may include new features, bug fixes, or security patches:
- Maintained: CrateDB will patch regressions, new and previously discovered bugs, as well as general improvements. Those are implemented when we have high confidence in their proper scoping and the fix won’t cause unintended side-effects.
- Supported: A new minor version puts the previous minor version into the "Supported" stage with limited releases for critical security and installation fixes only.
- End of Life: Minor versions that have reached EOL will no longer receive patch releases. EOL will be reach after one year after the first release in the minor version series. For example, 5.2.0 was released January 2, 2023 and EOL for 5.2 is January 1, 2024.
- Deprecated: CrateDB versions prior to 5.0.0 are no longer maintained by CrateDB nor supported in CrateDB Cloud.
CrateDB distinguishes between “maintained” and “supported” releases. Both allow customers with a valid support contract to open support tickets.
Maintained releases will receive pro-active regular maintenance updates until the release moves into a supported state.
For supported releases, customers with a valid support subscription can request backports of fixes and bug fixes into a supported version. Security fixes will be made available automatically for maintained and supported releases.
Only the last minor release (x.Y) of the current major release is maintained. The previous minor/feature release (x.Y-1.z) of a maintained minor/feature release with current major release is in a supported state. A currently maintained minor/feature release (x.Y.z) moves to a supported state with the release of a new minor/feature release (x.Y+1.z), at the same time the previously supported minor/feature release (x.Y-1.z) will be unsupported. For example, with the release of 6.3.0, only 6.3 will be maintained in the 6.x series, while the 6.2 series will be supported, and 6.1 will no longer be supported. The previous major release (X-1.y.z) will still be maintained in its latest minor release for up to six months after the release of a new major release. For example, version 5.10 will be maintained six months after the release of 6.0, and 5.9 and earlier will not be maintained.
The previous maintained minor/feature release moves into a supported state with the original release date of the following minor/feature release with major release (X.y.z). For example, with the release of CrateDB 6.0.0, the 5.10 series transitioned from a maintained to supported series.
Within the currently maintained CrateDB version only the last minor/feature release (x.Y.z) is being maintained. For example, with the release of CrateDB 6.2, the 6.1 series will be supported while 6.0 will no longer be supported, and it will not receive any bug fixes.
End of Life versions do not receive fixes anymore. For the best support, we recommend upgrading to a version that has been released within the last 12 months.
As part of support services, CrateDB may provide longer support terms.
