When physical cluster replication (PCR) is enabled, you must use the process on this page to upgrade your clusters. This process ensures that the standby cluster upgrades before the primary cluster.
The entire standby cluster must be on the same version as the primary cluster or a version the primary cluster can directly upgrade to. Within the primary and standby CockroachDB clusters, the system virtual cluster (SystemVC) must be at a cluster version greater than or equal to the app virtual cluster (AppVC).
Upgrade primary and standby clusters
To upgrade your primary and standby clusters:
Ensure that the virtual clusters on both your primary cluster and your standby cluster are finalized on the current version. If their versions have not been finalized, finalize them before beginning the upgrade process.
Upgrade the binaries on the standby cluster. Replace the binary on each node of the cluster and restart the node.
Finalize the upgrade on the standby cluster's SystemVC.
Note:If you need to roll back an upgrade, you must do so before the upgrade has been finalized.
After you have finalized the upgrade on the standby cluster's SystemVC, the clusters can remain in this state for an indefinite amount of time. You can wait to upgrade the primary cluster as long as is needed.
Upgrade the binaries on the primary cluster. Replace the binary on each node of the cluster and restart the node.
Finalize the upgrade on the primary cluster's SystemVC.
Note:If you need to roll back an upgrade, you must do so before the upgrade has been finalized. Rolling back the upgrade on the primary cluster does not also roll back the standby cluster.
Finalize the upgrade on the primary cluster's AppVC.
Upgrading the primary cluster's AppVC also upgrades the standby cluster's AppVC, since it replicates from the primary.
Upgrade ReaderVC
If you have a reader virtual cluster (ReaderVC), use the following steps to upgrade it by dropping and re-creating it:
- After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed.
On the standby cluster, stop the ReaderVC service:
ALTER VIRTUAL CLUSTER <readervc-name> STOP SERVICEDrop the ReaderVC:
DROP VIRTUAL CLUSTER <readervc-name>Back on the standby cluster, if the version is as expected, re-create the ReaderVC:
ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER
Failover and fast failback during upgrade
If you need to perform a failover while upgrading your clusters, you can do that using the normal process.
However, after performing a failover you cannot perform a fast failback to the original primary cluster during the upgrade process. This is because at times during the upgrade the standby cluster is ahead of the primary cluster.
Minor version upgrades
Minor versions are not relevant when determining PCR compatibility. There is no need to consider PCR compatibility when upgrading to a specific minor version within a major version.
