Now that CockroachDB v22.1 is available, an Org Administrator can upgrade your CockroachDB Dedicated cluster from the CockroachDB Cloud Console. This page guides you through the process for an Admin.
Upgrading a CockroachDB Dedicated cluster to a new major version is opt-in. Before proceeding, review the CockroachDB Cloud upgrade policy.
Step 1. Verify that you can upgrade
To upgrade to v22.1, you must be running v21.2. If you are not running v21.2, first upgrade to v21.2. 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.
Approximately 72 hours after all nodes are running v22.1, the upgrade will be automatically finalized. This enables certain features and performance improvements introduced in v22.1. Finalization also removes the ability to roll back to v21.2, so it's important to monitor your application during this 72-hour window and, if you see unexpected behavior, roll back the upgrade from the CockroachDB Cloud Console.
When you start the upgrade, the cluster will be unavailable for a few minutes while the node is stopped and restarted with v22.1.
Approximately 72 hours after the node has been restarted, the upgrade will be automatically finalized. This enables certain features and performance improvements introduced in v22.1. Finalization also removes the ability to roll back to v21.2, so it's important to monitor your application during this 72-hour window and, if you see unexpected behavior, roll back the upgrade from the CockroachDB Cloud Console.
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 v22.1. Prepare your application for this brief downtime, typically a few minutes.
The SQL Users and Tools pages in the CockroachDB Cloud Console will also be disabled during this time.
Review breaking changes
Review the backward-incompatible changes in v22.1 and deprecated features. 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 Start Upgrade.
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 v22.1.
Step 6. Monitor the upgrade
Once your cluster is running v22.1, you will have approximately 72 hours before the upgrade is automatically finalized. During this time, it is important to monitor your application and respect temporary limitations.
If you see unexpected behavior, you can roll back to v21.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 v21.2 during the 72-hour window.
Expect temporary limitations
Most v22.1 features can be used right away, but some will be enabled only after the upgrade has been finalized. Attempting to use these features before finalization will result in errors:
- SCRAM-SHA-256 authentication: CockroachDB supports SCRAM-SHA-256 authentication for clients in both CockroachDB Cloud and CockroachDB Self-Hosted. For SQL client sessions, it is now possible to use the authentication methods
password(cleartext passwords), andcert-password(TLS client cert or cleartext password) with either CRDB-BCRYPT or SCRAM-SHA-256 stored credentials. - Row-Level Time to Live (TTL): CockroachDB has preview support for Time to Live ("TTL") expiration on table rows, also known as Row-Level TTL. Row-Level TTL is a mechanism whereby rows from a table are considered "expired" and can be automatically deleted once those rows have been stored longer than a specified expiration time.
For an expanded list of features included in the v22.1 release, see the v22.1 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 v21.2, 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 v21.2 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 v21.2. 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, or you can manually finalize the upgrade to lift the temporary limitations on the cluster more quickly.
Finalize the upgrade
The upgrade is automatically finalized after 72 hours.
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, all temporary limitations will be lifted, and all v22.1 features are available for use. However, it will no longer be possible to roll back to v21.2. If you see unexpected behavior after the upgrade has been finalized, contact support.
See also
Was this helpful?
