| title | summary | toc | docs_area |
|---|---|---|---|
Upgrade to CockroachDB v20.2 |
Learn how to upgrade your CockroachDB cluster to v20.2. |
true |
manage |
Now that CockroachDB v20.2 is available, your Console Admin can upgrade your cluster directly from the {{ site.data.products.db }} Console. This page walks through the process.
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.
The upgrade process depends on the number of nodes in your cluster. Select whether your cluster has multiple nodes or a single node:
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 {{ site.data.products.db }} 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 {{ site.data.products.db }} Console.
Before starting the upgrade, it's important to complete the following steps.
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 Monitoring tabs in the {{ site.data.products.db }} Console will be disabled.
Review the backward-incompatible changes in v20.2, and if any affect your application, make necessary changes.
To start the upgrade process:
-
Sign in to your {{ site.data.products.db }} 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.
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.
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.
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.
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.
To finalize the upgrade, click Finalize in the banner at the top of the {{ site.data.products.db }} 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.
To stop the upgrade and roll back to v20.1, click Roll back in the banner at the top of the {{ site.data.products.db }} Console, and then click Roll back upgrade.