Now that CockroachDB v20.2 is available, your Org Administrator can upgrade your cluster directly from the CockroachDB Cloud Console. This page walks through the process.
Step 1. Verify that you can upgrade
To upgrade to v20.2, you must be running v20.1. If you are not running v20.1, upgrade to v20.1 and 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 process
In a multi-node cluster, the upgrade happens without interrupting the cluster's overall health and availability. One node is stopped and restarted with the new version, then the next, and so on, with a few minutes pause between each. In total, this "rolling upgrade" approach takes approximately 4-5 minutes per node and is possible due to CockroachDB's multi-active availability design.
Approximately 72 hours after all nodes are running v20.2, the upgrade will be automatically finalized. This enables certain features and performance improvements introduced in v20.2. Finalization also removes the ability to roll back to v20.1, so it's important to monitor your application during this 72-hour window and, if you see unexpected behavior, trigger a rollback 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 v20.2.
Approximately 72 hours after the node has been restarted, the upgrade will be automatically finalized. This enables certain features and performance improvements introduced in v20.2. Finalization also removes the ability to roll back to v20.1, so it's important to monitor your application during this 72-hour window and, if you see unexpected behavior, trigger a rollback from the CockroachDB Cloud Console.
Step 4. Prepare to upgrade
Before starting the upgrade, it's important to complete the following steps.
Prepare for brief unavailability
Because your cluster will be unavailable while its single node is stopped and restarted with v20.2, prepare your application for this brief downtime, typically a few minutes. Also during this time, the SQL Users and Tools tabs in the CockroachDB Cloud Console will be disabled.
Review breaking changes
Review the backward-incompatible changes in v20.2, and if any affect your application, make necessary changes.
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 cluster.
On the Upgrade your cluster dialog, confirm that you have reviewed the pre-upgrade guidance and then click Start Upgrade.
As mentioned earlier, your cluster will be upgraded one node at a time without interrupting the cluster's overall health and availability. This "rolling upgrade" approach will take approximately 4-5 minutes per node.
As mentioned earlier, your single-node cluster will be unavailable for a few minutes while the node is stopped and restarted with v20.2.
Step 6. Monitor the upgrade
Once your cluster is running v20.2, 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.
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 trigger finalization more quickly.
If you see unexpected behavior, you can rollback to v20.1. This option is available only during the 72-hour window. If you see unexpected behavior after the upgrade has been finalized, you will have to reach out to support.
Respect temporary limitations
Most v20.2 features can be used right away, but there are some that will be enabled only after the upgrade has been finalized. Attempting to use these features before then will result in errors:
Spatial features: After finalization, it will be possible to use spatial indexes, and spatial functions, as well as the ability to migrate spatial data from various formats such as Shapefiles, GeoJSON, GeoPackages, and OpenStreetMap.
ENUMdata types: After finalization, it will be possible to create and manage user-definedENUMdata types consisting of sets of enumerated, static values.Altering column data types: After finalization, it will be possible to alter column data types where column data must be rewritten.
User-defined schemas: After finalization, it will be possible to create user-defined logical schemas, as well alter user-defined schemas, drop user-defined schemas, and convert databases to user-defined schemas.
Foreign key index requirement: After finalization, it will no longer be required to have an index on the referencing columns of a
FOREIGN KEYconstraint.Minimum password length: After finalization, the
server.user_login.min_password_lengthcluster setting will be respected as the minimum length for passwords.Materialized views: After finalization, it will be possible to create materialized views, or views that store their selection query results on-disk.
CREATELOGINprivilege: After finalization, theCREATELOGINprivilege will be required to define or change authentication principals or their credentials.
Step 7. Finish the upgrade
During the 72-hour window before the upgrade is automatically finalized, if you see unexpected behavior, you can trigger a rollback to v20.1. If everything looks good, you also have the choice to finalize the upgrade more quickly so as to lift the temporary limitations in place during the upgrade.
Finalize the upgrade
To finalize the upgrade, click Finalize in the banner at the top of the CockroachDB Cloud Console, and then click Finalize upgrade.
At this point, all temporary limitations are lifted, and all v20.2 features are available for use. However, it's no longer possible to roll back to v20.1. If you see unexpected behavior, reach out to support.
Roll back the upgrade
To stop the upgrade and roll back to v20.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 v20.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 v20.1. Be sure to prepare for this brief unavailability before starting the rollback.
See also
Was this helpful?
