Upgrade to CockroachDB v22.2

On this page

Because of CockroachDB's multi-active availability design, you can perform a "rolling upgrade" of your CockroachDB cluster. This means that you can upgrade nodes one at a time without interrupting the cluster's overall health and operations.

This page describes how to upgrade to the latest v22.2 release, v22.2.19. To upgrade CockroachDB on Kubernetes, refer to single-cluster or multi-cluster instead.

Terminology

Before upgrading, review the CockroachDB release terminology:

• A new major release is performed every 6 months. The major version number indicates the year of release followed by the release number, which will be either 1 or 2. For example, the latest major release is v25.4 (also written as v25.4.0).
• Each supported major release is maintained across patch releases that fix crashes, security issues, and data correctness issues. Each patch release increments the major version number with its corresponding patch number. For example, patch releases of v25.4 use the format v25.4.x.
• All major and patch releases are suitable for production usage, and are therefore considered "production releases". For example, the latest production release is v25.4.2.
• Prior to an upcoming major release, alpha and beta releases and release candidates are made available. These "testing releases" are not suitable for production usage. They are intended for users who need early access to a feature before it is available in a production release. These releases append the terms alpha, beta, or rc to the version number.

Step 1. Verify that you can upgrade

Run cockroach sql against any node in the cluster to open the SQL shell. Then check your current cluster version:

> SHOW CLUSTER SETTING version;

To upgrade to v22.2.19, you must be running either:

• Any earlier v22.2 release: v22.2.0-alpha.1 to v22.2.18.

• A v22.1 production release: v22.1.0 to v22.1.22.

If you are running any other version, take the following steps before continuing on this page:

When you are ready to upgrade to v22.2.19, continue to step 2.

Step 2. Prepare to upgrade

Before starting the upgrade, complete the following steps.

Review breaking changes

Review the backward-incompatible changes in v22.2 and deprecated features. If any affect your deployment, make the necessary changes before starting the rolling upgrade to v22.2.

Check load balancing

Make sure your cluster is behind a load balancer, or your clients are configured to talk to multiple nodes. If your application communicates with a single node, stopping that node to upgrade its CockroachDB binary will cause your application to fail.

Check cluster health

Verify the overall health of your cluster using the DB Console:

• Under Node Status, make sure all nodes that should be live are listed as such. If any nodes are unexpectedly listed as SUSPECT or DEAD, identify why the nodes are offline and either restart them or decommission them before beginning your upgrade. If there are DEAD and non-decommissioned nodes in your cluster, it will not be possible to finalize the upgrade (either automatically or manually).

• Under Replication Status, make sure there are 0 under-replicated and unavailable ranges. Otherwise, performing a rolling upgrade increases the risk that ranges will lose a majority of their replicas and cause cluster unavailability. Therefore, it's important to identify and resolve the cause of range under-replication and/or unavailability before beginning your upgrade.

• In the Node List:

  • Make sure all nodes are on the same version. If any nodes are behind, upgrade them to the cluster's current version first, and then start this process over.

• In the Metrics dashboards:

  • Make sure CPU, memory, and storage capacity are within acceptable values for each node. Nodes must be able to tolerate some increase in case the new version uses more resources for your workload. If any of these metrics is above healthy limits, consider adding nodes to your cluster before beginning your upgrade.

Check decommissioned nodes

If your cluster contains partially-decommissioned nodes, they will block an upgrade attempt.

1. To check the status of decommissioned nodes, run the cockroach node status --decommission command:

   cockroach node status --decommission
   

   In the output, verify that the value of the membership field of each node is decommissioned. If any node's membership value is decommissioning, that node is not fully decommissioned.

2. If any node is not fully decommissioned, try the following:

   1. First, reissue the decommission command. The second command typically succeeds within a few minutes.
   2. If the second decommission command does not succeed, recommission and then decommission it again. Before continuing the upgrade, the node must be marked as decommissioned.

Step 3. Decide how the upgrade will be finalized

By default, after all nodes are running the new version, the upgrade process will be auto-finalized. This will enable certain features and performance improvements introduced in v22.2. However, it will no longer be possible to roll back to v22.1 if auto-finalization is enabled. In the event of a catastrophic failure or corruption, the only option will be to start a new cluster using the previous binary and then restore from one of the backups created prior to performing the upgrade. For this reason, we recommend disabling auto-finalization so you can monitor the stability and performance of the upgraded cluster before finalizing the upgrade, but note that you will need to follow all of the subsequent directions, including the manual finalization in step 6:

1. Upgrade to v22.1, if you haven't already.

2. Start the cockroach sql shell against any node in the cluster.

3. Set the cluster.preserve_downgrade_option cluster setting:

   SET CLUSTER SETTING cluster.preserve_downgrade_option = '22.1';
   

   It is only possible to set this setting to the current cluster version.

Features that require upgrade finalization

When upgrading from v22.1 to v22.2, certain features and performance improvements will be enabled only after finalizing the upgrade, including but not limited to:

• The CREATE FUNCTION statement creates user-defined functions.
• Trigram indexes are a type of inverted index used to efficiently search for strings in large tables without providing an exact search term (fuzzy search).
• Predicates and projections in CREATE CHANGEFEED statements. Projections allow users to emit specific columnar data, including computed columns, while predicates (i.e., filters) allow users to restrict the data that emits to only those events that match the filter.

For an expanded list of features included in the v22.2 release, see the v22.2 release notes.

Step 4. Perform the rolling upgrade

Follow these steps to perform the rolling upgrade. To upgrade CockroachDB on Kubernetes, refer to single-cluster or multi-cluster instead.

For each node in your cluster, complete the following steps. Be sure to upgrade only one node at a time, and wait at least one minute after a node rejoins the cluster to upgrade the next node. Simultaneously upgrading more than one node increases the risk that ranges will lose a majority of their replicas and cause cluster unavailability.

These steps perform an upgrade to the latest v22.2 release, v22.2.19.

1. Drain and shut down the node.

2. Visit What's New in v22.2? and download the CockroachDB v22.2.19 full binary for your architecture.

3. Extract the archive. In the following instructions, replace {COCKROACHDB_DIR} with the path to the extracted archive directory.

4. If you have a previous version of the cockroach binary in your $PATH, rename the outdated cockroach binary, and then move the new one into its place.

   If you get a permission error because the cockroach binary is located in a system directory, add sudo before each command. The binary will be owned by the effective user, which is root if you use sudo.

   i="$(which cockroach)"; mv "$i" "$i"_old
   

   cp -i {COCKROACHDB_DIR}/cockroach /usr/local/bin/cockroach
   

5. Start the node so that it can rejoin the cluster.

   Without a process manager like systemd, re-run the cockroach start command that you used to start the node initially, for example:

   cockroach start \
       --certs-dir=certs \
       --advertise-addr={node address} \
       --join={node1 address},{node2 address},{node3 address}
   

   If you are using systemd as the process manager, run this command to start the node:

   systemctl start {systemd config filename}