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 v24.3 instead.

Overview

CockroachDB offers the following types of upgrades:

• Major-version upgrades: A major-version upgrade moves a cluster from one major version of CockroachDB to another, such as from v24.2 to v24.3. A major-version upgrade 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, every second major version is an Innovation release. For CockroachDB Standard and CockroachDB Advanced, innovation releases offer shorter support windows and can be skipped. Innovation releases are required for CockroachDB Basic, and are applied automatically.

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

  Patch upgrades are automatically applied to CockroachDB Advanced, Standard, and Basic clusters.

  A major version of CockroachDB has two phases of patch releases: a series of testing releases followed by a series of production releases. A major version’s initial production release is also known as its GA release. In the lead-up to a new major version's GA release, a series of Testing 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 patch release, it will be automatically upgraded to subsequent patch releases within the major version, including newer Pre-Production Preview releases, the initial GA release, and subsequent patch releases.

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

CockroachDB v24.3 is a Regular release. To upgrade to it, you must be running either:

• v24.2, the previous Innovation release.
• v24.1, the previous Regular release.

Before continuing, upgrade to an appropriate version.

When you initiate a major-version upgrade, CockroachDB Cloud performs the following high-level steps, which are described in detail in the following sections.

1. On one node at a time:
   1. Replace the previous cockroach binary or container image with the new binary.
   2. Restart the cockroach process and verify that the node has rejoined the cluster.
2. When all nodes have rejoined the cluster:
   1. For a patch upgrade within the same major version, the upgrade is complete.
   2. For a major-version upgrade, the upgrade is not complete until it is finalized. Auto-finalization is enabled by default, and begins as soon as all nodes have rejoined the cluster using the new binary. If you need the ability to roll back a major-version upgrade, you can disable auto-finalization and finalize the upgrade manually. Certain features and performance improvements, such as those that require changes to system schemas or objects, are not available until the upgrade is finalized. Refer to the v24.3 Release Notes.

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 must be 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 v24.3 Release Notes, 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 view its descendants. 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, refer the CockroachDB Cloud Support Policy.

   To check whether major-version upgrades are available, click the three-dot Action 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.

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 remains fully available while it is upgraded. For a multi-node CockroachDB Advanced cluster, nodes are upgraded one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. 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. The dialog closes, and the Version column in the Cluster List page changes to Upgrading. When the upgrade has finished but has not yet been finalized, the Version column reports that the new version is pending.

The upgrade is not complete until it is finalized. After the upgrade is finalized, the cluster can no longer be rolled back to its previous major version. If you take no action, finalization occurs automatically after approximately 72 hours.

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
• v24.3 Release Notes