|
| 1 | +--- |
| 2 | +title: Upgrade with Physical Cluster Replication Enabled |
| 3 | +summary: Upgrade your primary and standby clusters when using PCR. |
| 4 | +toc: true |
| 5 | +docs_area: manage |
| 6 | +--- |
| 7 | + |
| 8 | +When [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) is enabled, you must use the process on this page to upgrade your clusters. This process ensures that the standby cluster safely upgrades before the primary cluster, preventing any version incompatibility. You cannot replicate data from a cluster on a newer version to a cluster on an older version. |
| 9 | + |
| 10 | +{{site.data.alerts.callout_info}} |
| 11 | +The entire standby cluster must be on the same major version as the primary cluster or a major version the primary cluster [can directly upgrade to]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#compatible-versions). Within the primary and standby CockroachDB clusters, the _system virtual cluster (SystemVC)_ must be at a cluster major version greater than or equal to the _app virtual cluster (AppVC)_. |
| 12 | +{{site.data.alerts.end}} |
| 13 | + |
| 14 | +## Upgrade primary and standby clusters |
| 15 | + |
| 16 | +To upgrade your primary and standby clusters: |
| 17 | + |
| 18 | +1. 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]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) them before beginning the upgrade process. |
| 19 | + |
| 20 | +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. Replace the binary on each node of the cluster and restart the node. |
| 21 | + |
| 22 | +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. |
| 23 | + |
| 24 | + {{site.data.alerts.callout_info}} |
| 25 | + If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized. |
| 26 | + {{site.data.alerts.end}} |
| 27 | + |
| 28 | +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. Replace the binary on each node of the cluster and restart the node. |
| 29 | + |
| 30 | +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. |
| 31 | + |
| 32 | + {{site.data.alerts.callout_info}} |
| 33 | + If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized. Rolling back the upgrade on the primary cluster does not roll back the standby cluster. |
| 34 | + {{site.data.alerts.end}} |
| 35 | + |
| 36 | +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's AppVC. |
| 37 | + |
| 38 | + Upgrading the primary cluster's AppVC also upgrades the standby cluster's AppVC, since it replicates from the primary. |
| 39 | + |
| 40 | +## Upgrade ReaderVC |
| 41 | + |
| 42 | +If you have a [_reader virtual cluster (ReaderVC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must upgrade it independently from the primary and standby clusters, after completing the main upgrade process. Use the following steps to upgrade your ReaderVC by dropping and re-creating it: |
| 43 | + |
| 44 | +1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. |
| 45 | +1. On the standby cluster, stop the ReaderVC service: |
| 46 | + |
| 47 | + {% include_cached copy-clipboard.html %} |
| 48 | + ~~~ sql |
| 49 | + ALTER VIRTUAL CLUSTER <readervc-name> STOP SERVICE; |
| 50 | + ~~~ |
| 51 | + |
| 52 | +1. Drop the ReaderVC: |
| 53 | + |
| 54 | + {% include_cached copy-clipboard.html %} |
| 55 | + ~~~ sql |
| 56 | + DROP VIRTUAL CLUSTER <readervc-name>; |
| 57 | + ~~~ |
| 58 | + |
| 59 | +1. On the standby cluster, re-create the ReaderVC: |
| 60 | + |
| 61 | + {% include_cached copy-clipboard.html %} |
| 62 | + ~~~ sql |
| 63 | + ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER; |
| 64 | + ~~~ |
| 65 | + |
| 66 | +At this point, the ReaderVC is on the same version as the standby cluster. |
| 67 | + |
| 68 | +## Failover and fast failback during upgrade |
| 69 | + |
| 70 | +If you need to, you can still perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. |
| 71 | + |
| 72 | +However, after performing a failover you cannot perform a [fast failback]({% link {{ page.version.version }}/failover-replication.md %}#failback) to the original primary cluster while the standby cluster version is newer than the primary cluster version. This is because you cannot replicate data from a cluster on a newer version to a cluster on an older version. |
| 73 | + |
| 74 | +## Minor version upgrades |
| 75 | + |
| 76 | +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. |
0 commit comments