Upgrade a cluster in CockroachDB Cloud

This page describes how major-version and patch upgrades work and shows how to upgrade a cluster in CockroachDB Cloud. To upgrade a CockroachDB self-hosted cluster, refer to Upgrade to v25.1 instead.

Overview

Types of upgrades

• Major-version upgrades: A major-version upgrade, such as from v24.2 to v24.3, may include new features, updates to cluster setting defaults, and backward-incompatible changes. Performing a major-version upgrade requires an additional step to finalize the upgrade.

  As of 2024, there are four major versions per year, where every second release is an innovation release. For CockroachDB Standard and CockroachDB Advanced, innovation releases offer shorter support windows and can be skipped. For CockroachDB Basic, all major version upgrades are applied automatically as they become available, including innovation releases.

• Patch upgrades: A patch upgrade moves a cluster from one patch release to another within a major version, such as from v24.2.3 to v24.2.4. Patch upgrades do not introduce backward-incompatible changes.

  A major version of CockroachDB has two phases of patch releases: a series of testing releases (beta, alpha, and RC releases) followed by a series of production releases (vX.Y.0, vX.Y.1, and so on). A major version’s first production release (the .0 release) is also known as its GA release.

  For CockroachDB Advanced, Standard, and Basic clusters, all production patch releases for a major version are automatically applied, until the cluster is upgraded to a new major version.

  • In the lead-up to a new major version's GA, a series of beta and RC releases may be made available to CockroachDB Advanced as Pre-Production Preview releases for testing and validation. Testing releases are intended for testing and experimentation only, and are not qualified for production environments or eligible for support or uptime SLA commitments.

  If a cluster is upgraded to a Pre-Production Preview release, it will be automatically upgraded to subsequent patch releases within the major version, including newer Pre-Production Preview testing releases, the GA release, and subsequent production patch releases.

To learn more about CockroachDB major versions and patches, refer to the Releases Overview.

Upgrade differences across Cloud plans

CockroachDB Cloud plan	Major version upgrades	Innovation releases
Basic	Automatic	Required
Standard	Automatic (default) or customer-initiated	Optional
Advanced	Customer-initiated	Optional

For all Cloud plans:

• All major versions that are Regular releases (as opposed to Innovation releases) are required upgrades before proceeding to a newer major version. To maintain support, an upgrade to a supported version must occur prior to the EOS date of the current version.
• Patch version upgrades occur automatically.

Compatible versions

A cluster may always be upgraded to the next major release once it is made available in CockroachDB Cloud. As of v24.1, for CockroachDB Standard and CockroachDB Advanced clusters, every second major verison is an Innovation release that can be skipped:

• If your cluster is running a major version that is a Regular release, it can be upgraded to either:

  • the next major version (an Innovation release)
  • the release that follows the next major version (the next Regular release, once it is available, skipping the Innovation release).

• If a cluster is running a major version that is labeled an Innovation release, it can be upgraded only to the next Regular release.

A list of currently supported major versions with links to their release notes is available in the CockroachDB Cloud Upgrade Policy.

Availability during an upgrade

For CockroachDB Standard and Basic, a cluster remains available during an upgrade.

For CockroachDB Advanced, nodes are upgraded one at a time in a rolling fashion. Multi-node clusters will remain available during the upgrade, but will have reduced capacity as each node restarts. Single-node clusters will be unavailable while the node restarts.

Upgrades and maintenance windows

If you have configured a maintenance window for a CockroachDB Advanced cluster, automatic patch upgrades are applied during the maintenance window. Major-version upgrades are initiated manually.

For more information, refer to the Cloud Upgrade Policy.

Prepare to upgrade

Before beginning a major-version upgrade:

1. Review the cluster's Metrics page to ensure that your cluster's compute and storage capacity is within acceptable values. The cluster must be able to tolerate some increase, in case the new version uses more resources for your workload. If any of these metrics is above healthy limits, consider increasing the cluster's resources before beginning your upgrade.
2. Managed backups are automated backups of CockroachDB Cloud clusters that are stored by Cockroach Labs in cloud storage. By default, Cockroach Labs takes and retains managed backups in all Cloud clusters.

When upgrading to a major release, you can optionally take a self-managed backup of your cluster to your own cloud storage, as an extra layer of protection in case the upgrade leads to issues.

1. Review the Release Notes for the major version to which you plan to upgrade, as well as the release notes for any skipped major version. Pay careful attention to the sections for backward-incompatible changes, deprecations, changes to default cluster settings, and features that are not available until the upgrade is finalized.

Perform a major-version upgrade

This section shows how to perform a major-version upgrade for a cluster in CockroachDB Cloud. Patch upgrades within a cluster's major version are applied automatically, and no action is required.

1. Verify the cluster's current major version, and which versions it can be upgraded to:
   1. Sign into CockroachDB Cloud.
   2. From the Clusters page, find the cluster by name. If the cluster is in a folder, click the name of the folder to find the cluster. The cluster's major version and patch are shown in the Version column.

2. Check which upgrades are available to the cluster, if any.

   Beginning with v24.1, major versions alternate in type between Regular releases, which are required, and Innovation releases, which can be skipped.

   From a Regular release, you can upgrade to the next major release (an Innovation release) or the subsequent major release (another Regular release). From an Innovation release, you must upgrade to the next Regular release.

   These releases also provide different support periods. For details on their support periods and which releases are Regular or Innovation releases, refer the CockroachDB Cloud Support Policy.

   To check whether major-version upgrades are available, click the three-dot Actions menu. If upgrades are available, Upgrade major version will be enabled. Click it. In the dialog, if only one newer major version upgrade is available, it is selected automatically. If multiple upgrades are available, the latest Regular release is selected by default. If you intend to upgrade the cluster, keep this dialog open while completing the next steps. Otherwise, close the dialog.

   In CockroachDB Standard, if the cluster is set to upgrade major versions automatically, the Actions menu will not show the Upgrade major version option. To change this setting, refer to Manage cluster upgrades.

3. Before beginning a major-version upgrade, review its Release notes, as well as the release notes for any skipped Innovation Releases. If any backward-incompatible changes or new features impact the cluster's workloads, you may need to make adjustments before beginning the upgrade.

4. A CockroachDB Standard or Basic cluster always remains available while it is upgraded. For a multi-node CockroachDB Advanced cluster, nodes are upgraded one at a time in a rolling fashion. The cluster remains available, even while one node at a time is temporarily unavailable during its upgrade. (Refer to Multi-Active Availability.) A single-node Advanced cluster will be unavailable while the cluster is upgraded and restarted. If necessary, prepare for the upgrade by communicating ahead of time with your users, and plan to begin the upgrade during a time when the impact on the cluster's workload will be minimized.

5. To begin a major-version upgrade, go back to the dialog in the CockroachDB Cloud Console. If multiple upgrades are available, select the desired version. Review the details, then click Start upgrade. After several seconds, the dialog closes, and the Version column in the Cluster List page changes to Upgrading, indicating the version to which you are upgrading the cluster.

6. To finalize the upgrade:

   • For CockroachDB Basic clusters and CockroachDB Standard clusters that are set to upgrade automatically, no further action is needed. Major version upgrades are automatically finalized when the upgrade is complete, and cannot be rolled back. When the upgrade is complete, the new version is displayed under the Version column.
   • For CockroachDB Advanced cluster and CockroachDB Standard clusters that are set to upgrade manually, when the upgrade has finished but has not yet been finalized, the Version column reports that the new version is pending finalization. The cluster will be finalized automatically after approximately 72 hours, if you take no further action. During the 72-hour period, you can choose to roll back the upgrade or manually finalize the upgrade early. Until the upgrade is finalized, certain new features may not be available. For details, refer to the release notes for the major version.

Finalize a major-version upgrade manually

To finalize a major-version upgrade of CockroachDB Advanced or CockroachDB Standard manually:

1. Click the cluster's name to open the Cluster Details page.

2. At the top of the page, click Finalize.

   When finalization begins, a series of migration jobs run to enable certain types of features and changes in the new major version that cannot be rolled back. These include changes to system schemas, indexes, and descriptors, and enabling certain types of improvements and new features.

   Until the upgrade is finalized, these features and functions will not be available, and the command SHOW CLUSTER SETTING version will continue to report the previous major version. Features that are available only after finalization are listed in the release notes for the new major version.

   You can monitor the process of finalization in the CockroachDB Cloud Jobs page. Migration jobs have names in the format {major-version}-{migration-id}. If a migration job fails or stalls, Cockroach Labs can use the migration ID to help diagnose and troubleshoot the problem. Each major version has a unique set of migration jobs and IDs.

When finalization is complete, the Cluster List and Cluster Details page report the new version, and you can no longer roll back to the previous major version.

Roll back a major-version upgrade

To roll back an CockroachDB Advanced cluster to the previous major version before the upgrade is finalized automatically:

1. Click the cluster's name to open the Cluster Details page.
2. At the top of the page, click Roll back.

A CockroachDB Standard cluster remains fully available while it is rolled back. For a multi-node CockroachDB Advanced cluster, nodes are rolled back one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node CockroachDB Advanced cluster will be unavailable while the cluster is rolled back and restarted.

Troubleshooting

After the upgrade has finalized (whether manually or automatically), it is no longer possible to roll back the upgrade. If you are experiencing problems, we recommend that you open a support request for assistance.

In the event of catastrophic failure or corruption, it may be necessary to restore from a backup to a new cluster running the previous major version.

See also

• Cloud Upgrade Policy
• v25.1 Release Notes
• Release notes for additional supported versions