Skip to content

Latest commit

 

History

History
134 lines (81 loc) · 9.4 KB

upgrade-to-v21.2.md

File metadata and controls

134 lines (81 loc) · 9.4 KB
title summary toc docs_area
Upgrade to CockroachDB v21.2
Learn how to upgrade your CockroachDB cluster to v21.2.
true
manage

Now that CockroachDB v21.2 is available, a Console Admin can upgrade your {{ site.data.products.dedicated }} cluster from the {{ site.data.products.db }} Console. This page guides you through the process for an Admin.

{{site.data.alerts.callout_success}} Upgrading a {{ site.data.products.dedicated }} cluster to a new major version is opt-in. Before proceeding, review the {{ site.data.products.db }} upgrade policy. {{site.data.alerts.end}}

Step 1. Verify that you can upgrade

To upgrade to v21.2, you must be running v21.1. If you are not running v21.1, first upgrade to v21.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:

  Multi-node   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. One node is stopped and restarted with the new version, then the next, and so on, pausing for a few minutes between each node. This "rolling upgrade" takes approximately 4-5 minutes per node and is enabled by CockroachDB's [multi-active availability](../{{site.versions["stable"]}}/multi-active-availability.html) design.

Approximately 72 hours after all nodes are running v21.2, the upgrade will be automatically finalized. This enables certain features and performance improvements introduced in v21.2. Finalization also removes the ability to roll back to v21.1, 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 {{ 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 v21.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 v21.2. Finalization also removes the ability to roll back to v21.1, 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 {{ site.data.products.db }} 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 v21.2. Prepare your application for this brief downtime, typically a few minutes.

The SQL Users and Monitoring tabs in the {{ site.data.products.db }} Console will also be disabled during this time.

Review breaking changes

Review the backward-incompatible changes in v21.2. If any affect your applications, make the necessary changes before proceeding.

Step 5. Start the upgrade

To start the upgrade process:

  1. Sign in to your {{ site.data.products.db }} account.

  2. In the Clusters list, select the cluster you want to upgrade.

  3. Select Actions > Upgrade major version.

  4. 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 v21.2.

Step 6. Monitor the upgrade

Once your cluster is running v21.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.

If you see unexpected behavior, you can roll back to v21.1 during the 72-hour window.

Monitor your application

Use the DB Console or your own tooling to monitor your application for any unexpected behavior.

Respect temporary limitations

Most v21.2 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:

  • Expression indexes: Indexes on expressions can now be created. These indexes speed up queries that filter on the result of that expression, and are especially useful for indexing only a specific field of a JSON object.
  • Privilege inheritance: CockroachDB's model for inheritance of privileges that cascade from schema objects now matches PostgreSQL. Added support for ALTER DEFAULT PRIVILEGES and SHOW DEFAULT PRIVILEGES.
  • Bounded staleness reads: Bounded staleness reads are now available in CockroachDB. These use a dynamic, system-determined timestamp to minimize staleness while being more tolerant to replication lag than exact staleness reads. This dynamic timestamp is returned by the with_min_timestamp() or with_max_staleness() functions. In addition, bounded staleness reads provide the ability to serve reads from local replicas even in the presence of network partitions or other failures.
  • Restricted and default placement: You can now use the ALTER DATABASE ... PLACEMENT RESTRICTED statement to constrain the replica placement for a multi-region database's regional tables to the home regions associated with those tables.
  • ON UPDATE expressions: An ON UPDATE expression can now be added to a column to update column values when an UPDATE or UPSERT statement modifies a different column value in the same row, or when an ON UPDATE CASCADE expression on a different column modifies an existing value in the same row.

For an expanded list of features included in the v21.2 release, see the v21.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 v21.1, click Roll back in the banner at the top of the {{ site.data.products.db }} Console, and then click Roll back upgrade.

During rollback, nodes will be reverted to v21.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 v21.1. Be sure to [prepare for this brief unavailability](#prepare-for-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 trigger finalization 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 {{ site.data.products.db }} Console, and then click Finalize upgrade.

After finalization, all temporary limitations will be lifted, and all v21.2 features are available for use. However, it will no longer be possible to roll back to v21.1. If you see unexpected behavior after the upgrade has been finalized, contact support.

See also