# 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.4 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 Advanced, Innovation releases include all of the latest features but have shorter support windows and can be skipped.

  For CockroachDB Standard and Basic, only Regular releases are supported. Major version upgrades are applied automatically to Standard and Basic clusters as they become available, and Standard clusters have the option to turn off automatic updates.

- 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 all CockroachDB Cloud clusters, production patch releases for a major version are automatically applied until the cluster is upgraded to a new major version. On an Advanced cluster, you have the option to defer patch updates for 30, 60, or 90 days if you have a maintenance window configured.

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 | Unavailable
Standard | Automatic (default) or customer-initiated | Unavailable
Advanced | Customer-initiated | Optional

Note:

For CockroachDB Basic clusters and CockroachDB Standard clusters that are set to upgrade automatically, major version upgrades are finalized immediately and cannot be rolled back. Basic and Standard clusters are upgraded to the .1 patch release of a major version, not the initial .0 release.

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 Regular release once it is made available in CockroachDB Cloud. Every second major version is an Innovation release that can be deployed or skipped on CockroachDB Advanced clusters:

- 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.

Note:

Maintenance operations that are critical for cluster security or stability may be applied outside of the maintenance window, and upgrades that begin in a maintenance window may not always be completed by the end of the window.

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.

   Major versions alternate between Regular releases, which are required, and Innovation releases, which can be skipped in Advanced clusters and are unavailabile in Standard or Basic.

   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.

Note:

CockroachDB Basic clusters are upgraded automatically and finalization is not required.

### 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.

Note:

Rolling back a major-version upgrade is not supported on Basic.

## 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.4 Release Notes
- Release notes for additional supported versions