This page describes the upgrade policy for CockroachDB Cloud. For self-hosted clusters, see the CockroachDB Release Support Policy.
Cockroach Labs uses a three-component calendar versioning scheme to name CockroachDB releases. The format is YY.R.PP, where YY indicates the year, R indicates the release (“1” or “2”, representing a typical biannual cycle), and PP indicates the patch release version. Example: Version 23.1.0 (abbreviated v23.1.0). Leading up to a new major version's initial GA (Generally Available) release, multiple testing builds are produced, moving from Alpha to Beta to Release Candidate. CockroachDB began using this versioning scheme with v19.1. For more details, refer to Release Naming.
CockroachDB Cloud supports the latest major version of CockroachDB and the major version immediately preceding it. Support for these versions includes patch version upgrades and security patches.
Prior to the GA release of a major CockroachDB version, CockroachDB Dedicated clusters can optionally be upgraded to a Pre-Production Preview release—a beta or release candidate (RC) testing release for testing and validation of that next major version. To learn more, refer to Upgrade to v23.2 Pre-Production Preview.
CockroachDB Serverless clusters are subject to automatic upgrades for both major and patch releases.
Patch version upgrades
Patch version releases, or "maintenance" releases, contain stable, backward-compatible improvements to the major versions of CockroachDB (for example, v23.1.12 and v23.1.13).
For CockroachDB Dedicated clusters, Org Administrators can set a weekly 6-hour maintenance window during which available maintenance and patch upgrades will be applied. During the window, your cluster may experience restarts, degraded performance, and downtime for single-node clusters. Upgrades may not always be completed by the end of the window, and maintenance that is critical for security or stability may occur outside the window. Patch upgrades can also be deferred for 60 days. If no maintenance window is configured, CockroachDB Dedicated clusters will be automatically upgraded to the latest supported patch version as soon as it becomes available.
CockroachDB Serverless clusters are subject to automatic upgrades to the latest supported patch version.
To minimize disruption to clients during cluster upgrades, it's important to use connection retry logic in your application.
Single-node clusters will experience some downtime during cluster maintenance.
Major version upgrades
Major version releases (for example, v23.1.0 and v23.2.0) contain new functionality and potentially backward-incompatible changes to CockroachDB.
Major version upgrades are automatic for CockroachDB Serverless clusters and opt-in for CockroachDB Dedicated clusters. Org Administrators must initiate major version upgrades for CockroachDB Dedicated clusters. When a new major version is available, Admins will be able to start an upgrade from the CockroachDB Cloud Console for clusters using the paid version of CockroachDB Dedicated. When a major version upgrade is initiated for a cluster, it will upgrade to the latest patch version as well.
Pre-production preview upgrades
Prior to the GA release of a major CockroachDB version, CockroachDB Cloud organizations can create new clusters or upgrade existing clusters to a Pre-Production Preview release for testing and experimentation using a beta or release candidate (RC) of that next major version. Upgrading to a Pre-Production Preview is a major-version upgrade. After a cluster is upgraded to a Pre-Production Preview release, it is automatically upgraded to all subsequent releases within the same major version—including additional beta and RC releases, the GA release, and subsequent patch releases after GA, as patch version upgrades. To learn more, refer to Upgrade to v23.2 Pre-Production Preview.
Rollback support
When upgrading a CockroachDB Dedicated cluster to a new major version, once all nodes are running the new version, you have approximately 72 hours before the upgrade is automatically finalized. During this window, if you see unexpected behavior, you can trigger a rollback to the previous major version from the CockroachDB Cloud Console.
To stop the upgrade and roll back to the latest patch release of the previous major version, click Roll back in the banner at the top of the CockroachDB Cloud Console, and then click Roll back upgrade.
If you choose to roll back a major version upgrade, your cluster will be rolled back to the latest patch release of the previous major version, which may differ from the patch release you were running before you initiated the upgrade.
During rollback, nodes are reverted to that prior version one at a time, without interrupting the cluster's health and availability.
If you see problems after a major version upgrade has been finalized, it will not be possible to roll back via the CockroachDB Cloud Console. For assistance, contact support.
End of Support for older CockroachDB versions
As CockroachDB releases new major versions, older versions reach their End of Support (EOS) on CockroachDB Cloud. A CockroachDB version reaches EOS when it is two major versions behind the latest version. For example, when CockroachDB v21.2 was released, CockroachDB v20.2 reached EOS.
Clusters running unsupported CockroachDB versions are not eligible for our availability SLA. Further downgrades in support may occur as per the CockroachDB Release Support Policy.
If you are running a CockroachDB version nearing EOS, you will be reminded at least one month before that version’s EOS that your clusters must be upgraded by the EOS date to avoid losing support. A Org Administrator can upgrade your cluster directly from the CockroachDB Cloud Console.
See also
For more details about the upgrade and finalization process, see Upgrade to the Latest CockroachDB Version.
Was this helpful?
