CockroachDB v24.2 is available to CockroachDB Advanced clusters as an opt-in upgrade. An Org Administrator can upgrade your CockroachDB Advanced cluster from the CockroachDB Cloud Console. This page shows how to upgrade a CockroachDB Advanced cluster to . This page shows how to upgrade a CockroachDB Advanced cluster to Pre-Production Preview.
Upgrading from v24.1 to v24.2 is a major-version upgrade. Upgrading a CockroachDB Advanced cluster to a new major version is opt-in. Before proceeding, review the CockroachDB Cloud Upgrade Policy. After a cluster is upgraded, it is automatically upgraded to all subsequent releases within the same major version as patch version upgrades. To learn more, refer to Patch Version Upgrades.
All CockroachDB Basic clusters are upgraded automatically to new patch versions, as well as new major versions, to maintain uninterrupted support and SLA guarantees. This is also the default for CockroachDB Standard.
CockroachDB v24.2 is an Innovation release, which is optional for CockroachDB Advanced, required by default for CockroachDB Standard clusters, and required for CockroachDB Basic
Refer to CockroachDB Cloud Upgrade Policy before installing or upgrading for release timing and support details.
Step 1. Verify that you can upgrade
To upgrade to CockroachDB v24.2, you must be running v24.1. If you are not running v24.1, first upgrade to v24.1. Then return to this page and continue to Step 2.
Step 2. Select your cluster size
The upgrade process depends on the number of nodes in your cluster. Select whether your cluster has multiple nodes or a single node:
Step 3. Understand the upgrade process
In a multi-node cluster, the upgrade does not interrupt the cluster's overall health and availability. CockroachDB Cloud stops one node at a time and restarts it with the new version, waits a few minutes to observe the upgraded node's behavior, then moves on to the next node. This "rolling upgrade" takes approximately 4-5 minutes per node and is enabled by CockroachDB's multi-active availability design.
When you start the upgrade, the cluster will be unavailable for a few minutes while the node is stopped and restarted with v24.2.
If you are upgrading from to v24.2, the upgrade must be finalized. This is not required for subsequent patch upgrades. Approximately 72 hours after all nodes are running v24.2, the upgrade will be automatically finalized. It's important to monitor your cluster and applications during this 72-hour window, so that you can roll back the upgrade from the CockroachDB Cloud Console if you see unexpected behavior according to key metrics or if you experience application or database issues.
During a major-version upgrade, certain features and performance improvements may not be available until the upgrade is finalized. However, when upgrading to v24.2, all features are available immediately, and no features require finalization.
Finalization is always required to complete an upgrade.
When finalization is complete, it is no longer possible to roll back to v24.1.
If you choose to roll back a major version upgrade, your cluster will be rolled back to the latest patch release of v24.1, which may differ from the patch release you were running before you initiated the upgrade. To learn more, refer to CockroachDB Cloud Upgrade Policy.
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 return 24.2.
You can monitor the process of the migration in the CockroachDB Cloud Jobs page. Migration jobs have names in the format 24.1-{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 different migration jobs with different IDs.
Finalization is complete when all migration jobs have completed. After migration is complete, the command SHOW CLUSTER SETTING version will return 24.1.
Step 4. Prepare to upgrade
Before starting the upgrade, complete the following steps.
Prepare for brief unavailability
Your cluster will be unavailable while its single node is stopped and restarted with v24.2. Prepare your application for this brief downtime, typically a few minutes.
The SQL Users and Tools tabs in the CockroachDB Cloud Console will also be disabled during this time.
Review breaking changes
Review the backward-incompatible changes and deprecated features announced in the v24.2 release notes. If any affect your applications, make the necessary changes before proceeding.
Step 5. Start the upgrade
To start the upgrade process:
Sign in to your CockroachDB Cloud account.
In the Clusters list, select the cluster you want to upgrade.
Select Actions > Upgrade major version.
In the Upgrade your cluster dialog, review the pre-upgrade message and then click major version.
Your cluster will be upgraded one node at a time without interrupting the cluster's overall health and availability. This "rolling upgrade" will take approximately 4-5 minutes per node.
Your single-node cluster will be unavailable for a few minutes while the node is stopped and restarted with CockroachDB v24.2.
After it is started, an upgrade cannot be cancelled. Instead, you can wait for the upgrade to finish, then roll it back for up to 72 hours, after which time it will be finalized and cannot be rolled back.
Step 6. Monitor the upgrade
Once your cluster is running CockroachDB v24.2, you will have approximately 72 hours before the upgrade is automatically finalized. During this time, it is important to monitor your applications and expect temporary limitations.
If you see unexpected behavior, you can roll back to v24.2 during the 72-hour window.
Monitor your application
Use the DB Console or your own tooling to monitor your application for any unexpected behavior.
If everything looks good, you can wait for the upgrade to automatically finalize or you can manually trigger finalization.
If you see unexpected behavior, you can roll back to the latest patch release of v24.1 during the 72-hour window.
Expect temporary limitations
All v24.2 features can be used right away. However, finalization is always required to complete a major-version upgrade.
For an expanded list of features included in v24.2, temporary limitations, backward-incompatible changes, and deprecated features, refer to the v24.2 release notes.
Roll back the upgrade
If you see unexpected behavior, you can roll back the upgrade during the 72-hour window.
To stop the upgrade and roll back to v24.1, click Roll back in the banner at the top of the CockroachDB Cloud Console, and then click Roll back upgrade.
During rollback, nodes will be reverted to the latest production patch release of v24.1 one at a time without interrupting the cluster's health and availability.
Because your cluster contains a single node, the cluster will be briefly unavailable while the node is stopped and restarted with the latest production patch release of v24.1. Be sure to prepare for this brief unavailability before starting the rollback.
Step 7. Complete the upgrade
If everything looks good, you can wait for the upgrade to automatically finalize after 72 hours, or you can manually finalize the upgrade to lift any temporary limitations on the cluster more quickly.
To manually finalize the upgrade, click Finalize in the banner at the top of the CockroachDB Cloud Console, and then click Finalize upgrade.
After finalization, any temporary limitations will be lifted and all v24.2 features will be available for use. No such features exist for v24.2.
After finalization, it will no longer be possible to roll back to v24.1. If you see unexpected behavior after the upgrade has been finalized, contact support.
See also
Was this helpful?
