Upgrade to CockroachDB v23.2

Now that CockroachDB v23.2 is available, an Org Administrator can upgrade your CockroachDB Advanced cluster from the CockroachDB Cloud Console. This page guides you through the process for an Admin.

If you upgrade to a Pre-Production Preview of v23.2, your cluster will be automatically upgraded to v23.2.0 upon its GA release.

Step 1. Verify that you can upgrade

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

If you are upgrading from v23.1 to v23.2, the upgrade must be finalized. This is not required for subsequent patch upgrades. Approximately 72 hours after all nodes are running v23.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. Finalization enables certain features and performance improvements introduced in v23.2. When finalization is complete, it is no longer possible to roll back to v23.1.

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 23.1.

You can monitor the process of the migration in the CockroachDB Cloud Jobs page. Migration jobs have names in the format 23.2-{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 23.2.

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 v23.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 v23.2 release notes

Step 5. Start the upgrade

To start the upgrade process:

1. Sign in to your CockroachDB Cloud 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 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 v23.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 v23.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 v23.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.

• 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 v23.1 during the 72-hour window.

Expect temporary limitations

Most v23.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:

• The coalescing of storage ranges for each table, index, or partition (collectively referred to as "schema objects") into a single range when individual schema objects are smaller than the default configured maximum range size (controlled using zone configs, specifically the range_max_bytes parameter). This change improves scalability with respect to the number of schema objects, since the underlying range count is no longer a potential performance bottleneck. After finalizing the upgrade to v23.2, you may observe a round of range merges and snapshot transfers. To disable this optimization, before finalizing the upgrade, set the spanconfig.storage_coalesce_adjacent.enabled cluster setting to false. Refer to the v23.1 release notes for SHOW RANGES for more details. #102961
• The new output log format, which allows configuration of a time zone in log output. Before configuring a time zone, the cluster must be finalized on v23.2. #104265
• Performance improvements when a node reclaims disk space. #106177
• The following admission control mechanisms, which help to maintain cluster performance and availability when some nodes experience high load:
  • Delete operations
  • Replication
  #98308
  • Collecting a statement diagnostic bundle for a particular plan. The existing fingerprint-based matching has been extended to also include plan-gist-based matching and "anti-matching" (collecting a bundle for any plan other than the provided plan gist). #105477
  • A new system table, system.region_liveness, that tracks the availability and the timestamp of the latest unavailability for each cluster region. #107903
  • The ability of a WaitPolicy_Error request to push the timestamp of a transaction with a lower priority. #108190
  • Configuring a changefeed with the lagging_ranges_threshold or lagging_ranges_polling_interval changefeed options. #110649
  • Removal of the upgrade step grantExecuteToPublicOnAllFunctions, which is no longer required because post-serialization changes now grant EXECUTE on functions to the public role. #114203
  • A fix to a bug that could allow a user to execute a user-defined function without the EXECUTE privilege on the function. If a user does not have the privilege, the user-defined function does not run and an error is logged. #114203

  For an expanded list of features included in v23.2, temporary limitations, backward-incompatible changes, and deprecated features, refer to the v23.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 v23.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 v23.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 v23.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, 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 v23.2 features will be available for use. However, it will no longer be possible to roll back to v23.1. If you see unexpected behavior after the upgrade has been finalized, contact support.

  See also

  • CockroachDB Cloud Upgrade Policy
  • CockroachDB v23.2 Release Notes

  Was this helpful?