From 6020673efe87d5875fa4b28c999d8753e84c392f Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 21 Oct 2025 11:23:16 -0400 Subject: [PATCH 01/13] Added pcr upgrade page Added new page on the upgrade process with pcr enabled, including more detailed and accurate info than we had previously --- .../cross-cluster-replication.json | 6 ++ .../physical-cluster-replication-overview.md | 14 --- src/current/v25.3/upgrade-with-pcr.md | 87 +++++++++++++++++++ 3 files changed, 93 insertions(+), 14 deletions(-) create mode 100644 src/current/v25.3/upgrade-with-pcr.md diff --git a/src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json b/src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json index d9ee279f835..d9d997e0b54 100644 --- a/src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json +++ b/src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json @@ -46,6 +46,12 @@ "/${VERSION}/set-up-physical-cluster-replication.html" ] }, + { + "title": "Upgrade with Physical Cluster Replication Enabled", + "urls": [ + "/${VERSION}/upgrade-with-pcr.html" + ] + }, { "title": "Fail Over from a Primary to a Standby Cluster", "urls": [ diff --git a/src/current/v25.3/physical-cluster-replication-overview.md b/src/current/v25.3/physical-cluster-replication-overview.md index 65b332607ca..3ec0623a085 100644 --- a/src/current/v25.3/physical-cluster-replication-overview.md +++ b/src/current/v25.3/physical-cluster-replication-overview.md @@ -67,20 +67,6 @@ Statement | Action [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters. [`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. -## Cluster versions and upgrades - -{{site.data.alerts.callout_info}} -The entire standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster. -{{site.data.alerts.end}} - -When PCR is enabled, upgrade with the following procedure. This upgrades the standby cluster before the primary cluster. Within the primary and standby CockroachDB clusters, the system virtual cluster must be at a cluster version greater than or equal to the virtual cluster: - -1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary and standby clusters. Replace the binary on each node of the cluster and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's virtual cluster. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's virtual cluster. - ## Demo video Learn how to use PCR to meet your RTO and RPO requirements with the following demo: diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md new file mode 100644 index 00000000000..27a2359d1c8 --- /dev/null +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -0,0 +1,87 @@ +--- +title: Upgrade with Physical Cluster Replication Enabled +summary: Upgrade your clusters when using PCR. +toc: true +docs_area: manage +--- + +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 upgrades before the primary cluster. + +{{site.data.alerts.callout_info}} +The entire standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster. 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)_. +{{site.data.alerts.end}} + +## Upgrade primary and standby clusters + +To upgrade your primary and standby clusters: + +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. + + After upgrading the binaries on the standby cluster, the primary cluster is not upgradable until the standby cluster's upgrade has finalized. + + If auto-finalization is enabled, the upgrade auto-finalizes after 72 hours. + +1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. + + {{site.data.alerts.callout_info}} + 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. + {{site.data.alerts.end}} + +1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's AppVC. + + After you have finalized the upgrade on the standby cluster's AppVC, 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. + +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. + + After upgrading the binaries on the primary cluster, the standby cluster is not upgradable until the primary cluster's upgrade has finalized. + +1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. + + {{site.data.alerts.callout_info}} + 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. + {{site.data.alerts.end}} + +1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's AppVC. + +## Upgrade ReaderVC + +If you have a [_reader virtual cluster (ReaderVC)_]({% link {{ page.version.version }}/read-from-standby.md %}), use the following steps to upgrade it by dropping and re-creating it: + +1. After upgrading the AppVCs on your primary and standby clusters, wait for the replicated time to pass the time at which the upgrade completed. +1. On the standby cluster, stop the ReaderVC service: + + {% include_cached copy-clipboard.html %} + ~~~ sql + ALTER VIRTUAL CLUSTER STOP SERVICE + ~~~ + +1. Drop the ReaderVC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + DROP VIRTUAL CLUSTER + ~~~ + +1. On the AppVC, double-check that the standby cluster's AppVC has upgraded: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SHOW CLUSTER SETTING version + ~~~ + +1. Back on the standby cluster, if the version is as expected, re-create the ReaderVC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER + ~~~ + +## Failover and fast failback during upgrade + +If you need to perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters, you can do that using the normal process. + +However, after performing a failover you cannot perform a [fast failback]({% link {{ page.version.version }}/failover-replication.md %}#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. + +## Patch deferrals + +Patch versions are not relevant when determining PCR compatibility. There is no need to consider PCR compatibility when upgrading to a specific patch version within a major version. \ No newline at end of file From 9071e7def7adfe173de946452bf57a60201034a0 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 21 Oct 2025 15:06:58 -0400 Subject: [PATCH 02/13] summary length Fixed summary to be the right length --- src/current/v25.3/upgrade-with-pcr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md index 27a2359d1c8..63467747238 100644 --- a/src/current/v25.3/upgrade-with-pcr.md +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -1,6 +1,6 @@ --- title: Upgrade with Physical Cluster Replication Enabled -summary: Upgrade your clusters when using PCR. +summary: Upgrade your primary and standby clusters when using PCR. toc: true docs_area: manage --- From 0594686b2322b5a39e664663c04b416dd6eab298 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Wed, 22 Oct 2025 10:35:22 -0400 Subject: [PATCH 03/13] Quick changes from review A few small adjustments based on tech review --- src/current/v25.3/upgrade-with-pcr.md | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md index 63467747238..2c42d076dac 100644 --- a/src/current/v25.3/upgrade-with-pcr.md +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -8,7 +8,7 @@ docs_area: manage 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 upgrades before the primary cluster. {{site.data.alerts.callout_info}} -The entire standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster. 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)_. +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)_. {{site.data.alerts.end}} ## Upgrade primary and standby clusters @@ -27,9 +27,7 @@ To upgrade your primary and standby clusters: 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. {{site.data.alerts.end}} -1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's AppVC. - - After you have finalized the upgrade on the standby cluster's AppVC, 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. + 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. 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. @@ -38,16 +36,18 @@ To upgrade your primary and standby clusters: 1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. {{site.data.alerts.callout_info}} - 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. + 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 also roll back the standby cluster. {{site.data.alerts.end}} -1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's AppVC. +1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) 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)_]({% link {{ page.version.version }}/read-from-standby.md %}), use the following steps to upgrade it by dropping and re-creating it: -1. After upgrading the AppVCs on your primary and standby clusters, wait for the replicated time to pass the time at which the upgrade completed. +1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the ReaderVC service: {% include_cached copy-clipboard.html %} @@ -62,13 +62,6 @@ If you have a [_reader virtual cluster (ReaderVC)_]({% link {{ page.version.vers DROP VIRTUAL CLUSTER ~~~ -1. On the AppVC, double-check that the standby cluster's AppVC has upgraded: - - {% include_cached copy-clipboard.html %} - ~~~ sql - SHOW CLUSTER SETTING version - ~~~ - 1. Back on the standby cluster, if the version is as expected, re-create the ReaderVC: {% include_cached copy-clipboard.html %} @@ -82,6 +75,6 @@ If you need to perform a [failover]({% link {{ page.version.version }}/failover- However, after performing a failover you cannot perform a [fast failback]({% link {{ page.version.version }}/failover-replication.md %}#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. -## Patch deferrals +## Minor version upgrades -Patch versions are not relevant when determining PCR compatibility. There is no need to consider PCR compatibility when upgrading to a specific patch version within a major version. \ No newline at end of file +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. \ No newline at end of file From 8a2903c9a0315c012f4bcaa46d11deb9cb7f888d Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Thu, 23 Oct 2025 15:36:03 -0400 Subject: [PATCH 04/13] More changes from review Removed cloud only components and adjusting steps to match source of truth doc --- src/current/v25.3/upgrade-with-pcr.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md index 2c42d076dac..3111be70709 100644 --- a/src/current/v25.3/upgrade-with-pcr.md +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -15,13 +15,11 @@ The entire standby cluster must be on the same version as the primary cluster or To upgrade your primary and standby clusters: -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. - - After upgrading the binaries on the standby cluster, the primary cluster is not upgradable until the standby cluster's upgrade has finalized. +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. - If auto-finalization is enabled, the upgrade auto-finalizes after 72 hours. +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. -1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. {{site.data.alerts.callout_info}} 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. @@ -31,15 +29,13 @@ To upgrade your primary and standby clusters: 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. - After upgrading the binaries on the primary cluster, the standby cluster is not upgradable until the primary cluster's upgrade has finalized. - -1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. {{site.data.alerts.callout_info}} 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 also roll back the standby cluster. {{site.data.alerts.end}} -1. If auto-finalization is disabled, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's AppVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) 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. From a58a0532c57b301a18ac96d0430865d532dc860c Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Mon, 27 Oct 2025 13:23:16 -0400 Subject: [PATCH 05/13] More changes from review Some rewordings --- src/current/v25.3/upgrade-with-pcr.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md index 3111be70709..caf360faf47 100644 --- a/src/current/v25.3/upgrade-with-pcr.md +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -5,10 +5,10 @@ toc: true docs_area: manage --- -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 upgrades before the primary cluster. +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. {{site.data.alerts.callout_info}} -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)_. +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)_. {{site.data.alerts.end}} ## Upgrade primary and standby clusters @@ -25,14 +25,12 @@ To upgrade your primary and standby clusters: 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. {{site.data.alerts.end}} - 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. - 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. 1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. {{site.data.alerts.callout_info}} - 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 also roll back the standby cluster. + 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. {{site.data.alerts.end}} 1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's AppVC. @@ -41,35 +39,37 @@ To upgrade your primary and standby clusters: ## Upgrade ReaderVC -If you have a [_reader virtual cluster (ReaderVC)_]({% link {{ page.version.version }}/read-from-standby.md %}), use the following steps to upgrade it by dropping and re-creating it: +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: 1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the ReaderVC service: {% include_cached copy-clipboard.html %} ~~~ sql - ALTER VIRTUAL CLUSTER STOP SERVICE + ALTER VIRTUAL CLUSTER STOP SERVICE; ~~~ 1. Drop the ReaderVC: {% include_cached copy-clipboard.html %} ~~~ sql - DROP VIRTUAL CLUSTER + DROP VIRTUAL CLUSTER ; ~~~ -1. Back on the standby cluster, if the version is as expected, re-create the ReaderVC: +1. On the standby cluster, re-create the ReaderVC: {% include_cached copy-clipboard.html %} ~~~ sql - ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER + ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER; ~~~ +At this point, the ReaderVC is on the same version as the standby cluster. + ## Failover and fast failback during upgrade -If you need to perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters, you can do that using the normal process. +If you need to, you can still perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. -However, after performing a failover you cannot perform a [fast failback]({% link {{ page.version.version }}/failover-replication.md %}#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. +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. ## Minor version upgrades From eb0cf17b74d680643936b868752b63d61c973dac Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Mon, 27 Oct 2025 15:13:35 -0400 Subject: [PATCH 06/13] Back/forward port Ported to 24.3, 25.2, 25.4 --- .../cross-cluster-replication.json | 6 ++ .../cross-cluster-replication.json | 6 ++ .../cross-cluster-replication.json | 6 ++ .../physical-cluster-replication-overview.md | 14 ---- src/current/v24.3/upgrade-with-pcr.md | 76 +++++++++++++++++++ .../physical-cluster-replication-overview.md | 14 ---- src/current/v25.2/upgrade-with-pcr.md | 76 +++++++++++++++++++ src/current/v25.3/upgrade-with-pcr.md | 2 +- .../physical-cluster-replication-overview.md | 14 ---- src/current/v25.4/upgrade-with-pcr.md | 76 +++++++++++++++++++ 10 files changed, 247 insertions(+), 43 deletions(-) create mode 100644 src/current/v24.3/upgrade-with-pcr.md create mode 100644 src/current/v25.2/upgrade-with-pcr.md create mode 100644 src/current/v25.4/upgrade-with-pcr.md diff --git a/src/current/_includes/v24.3/sidebar-data/cross-cluster-replication.json b/src/current/_includes/v24.3/sidebar-data/cross-cluster-replication.json index 925e3e2aca9..1167c9e9e42 100644 --- a/src/current/_includes/v24.3/sidebar-data/cross-cluster-replication.json +++ b/src/current/_includes/v24.3/sidebar-data/cross-cluster-replication.json @@ -46,6 +46,12 @@ "/${VERSION}/set-up-physical-cluster-replication.html" ] }, + { + "title": "Upgrade with Physical Cluster Replication Enabled", + "urls": [ + "/${VERSION}/upgrade-with-pcr.html" + ] + }, { "title": "Fail Over from a Primary to a Standby Cluster", "urls": [ diff --git a/src/current/_includes/v25.2/sidebar-data/cross-cluster-replication.json b/src/current/_includes/v25.2/sidebar-data/cross-cluster-replication.json index 925e3e2aca9..1167c9e9e42 100644 --- a/src/current/_includes/v25.2/sidebar-data/cross-cluster-replication.json +++ b/src/current/_includes/v25.2/sidebar-data/cross-cluster-replication.json @@ -46,6 +46,12 @@ "/${VERSION}/set-up-physical-cluster-replication.html" ] }, + { + "title": "Upgrade with Physical Cluster Replication Enabled", + "urls": [ + "/${VERSION}/upgrade-with-pcr.html" + ] + }, { "title": "Fail Over from a Primary to a Standby Cluster", "urls": [ diff --git a/src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json b/src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json index d9ee279f835..d9d997e0b54 100644 --- a/src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json +++ b/src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json @@ -46,6 +46,12 @@ "/${VERSION}/set-up-physical-cluster-replication.html" ] }, + { + "title": "Upgrade with Physical Cluster Replication Enabled", + "urls": [ + "/${VERSION}/upgrade-with-pcr.html" + ] + }, { "title": "Fail Over from a Primary to a Standby Cluster", "urls": [ diff --git a/src/current/v24.3/physical-cluster-replication-overview.md b/src/current/v24.3/physical-cluster-replication-overview.md index 8c2c57c8bc9..3188d443053 100644 --- a/src/current/v24.3/physical-cluster-replication-overview.md +++ b/src/current/v24.3/physical-cluster-replication-overview.md @@ -69,20 +69,6 @@ Statement | Action [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters. [`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. -## Cluster versions and upgrades - -{{site.data.alerts.callout_info}} -The entire standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster. -{{site.data.alerts.end}} - -When PCR is enabled, upgrade with the following procedure. This upgrades the standby cluster before the primary cluster. Within the primary and standby CockroachDB clusters, the system virtual cluster must be at a cluster version greater than or equal to the virtual cluster: - -1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary and standby clusters. Replace the binary on each node of the cluster and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's virtual cluster. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's virtual cluster. - ## Demo video Learn how to use PCR to meet your RTO and RPO requirements with the following demo: diff --git a/src/current/v24.3/upgrade-with-pcr.md b/src/current/v24.3/upgrade-with-pcr.md new file mode 100644 index 00000000000..6698490c59c --- /dev/null +++ b/src/current/v24.3/upgrade-with-pcr.md @@ -0,0 +1,76 @@ +--- +title: Upgrade with Physical Cluster Replication Enabled +summary: Upgrade your primary and standby clusters when using PCR. +toc: true +docs_area: manage +--- + +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. + +{{site.data.alerts.callout_info}} +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)_. +{{site.data.alerts.end}} + +## Upgrade primary and standby clusters + +To upgrade your primary and standby clusters: + +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. + +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. + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. + + {{site.data.alerts.callout_info}} + 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. + {{site.data.alerts.end}} + +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. + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. + + {{site.data.alerts.callout_info}} + 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. + {{site.data.alerts.end}} + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) 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)_]({% 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: + +1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. +1. On the standby cluster, stop the ReaderVC service: + + {% include_cached copy-clipboard.html %} + ~~~ sql + ALTER VIRTUAL CLUSTER STOP SERVICE; + ~~~ + +1. Drop the ReaderVC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + DROP VIRTUAL CLUSTER ; + ~~~ + +1. On the standby cluster, re-create the ReaderVC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER; + ~~~ + +At this point, the ReaderVC is on the same version as the standby cluster. + +## Failover and fast failback during upgrade + +If you need to, you can still perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. + +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. + +## 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. \ No newline at end of file diff --git a/src/current/v25.2/physical-cluster-replication-overview.md b/src/current/v25.2/physical-cluster-replication-overview.md index 65b332607ca..3ec0623a085 100644 --- a/src/current/v25.2/physical-cluster-replication-overview.md +++ b/src/current/v25.2/physical-cluster-replication-overview.md @@ -67,20 +67,6 @@ Statement | Action [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters. [`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. -## Cluster versions and upgrades - -{{site.data.alerts.callout_info}} -The entire standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster. -{{site.data.alerts.end}} - -When PCR is enabled, upgrade with the following procedure. This upgrades the standby cluster before the primary cluster. Within the primary and standby CockroachDB clusters, the system virtual cluster must be at a cluster version greater than or equal to the virtual cluster: - -1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary and standby clusters. Replace the binary on each node of the cluster and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's virtual cluster. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's virtual cluster. - ## Demo video Learn how to use PCR to meet your RTO and RPO requirements with the following demo: diff --git a/src/current/v25.2/upgrade-with-pcr.md b/src/current/v25.2/upgrade-with-pcr.md new file mode 100644 index 00000000000..6698490c59c --- /dev/null +++ b/src/current/v25.2/upgrade-with-pcr.md @@ -0,0 +1,76 @@ +--- +title: Upgrade with Physical Cluster Replication Enabled +summary: Upgrade your primary and standby clusters when using PCR. +toc: true +docs_area: manage +--- + +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. + +{{site.data.alerts.callout_info}} +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)_. +{{site.data.alerts.end}} + +## Upgrade primary and standby clusters + +To upgrade your primary and standby clusters: + +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. + +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. + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. + + {{site.data.alerts.callout_info}} + 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. + {{site.data.alerts.end}} + +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. + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. + + {{site.data.alerts.callout_info}} + 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. + {{site.data.alerts.end}} + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) 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)_]({% 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: + +1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. +1. On the standby cluster, stop the ReaderVC service: + + {% include_cached copy-clipboard.html %} + ~~~ sql + ALTER VIRTUAL CLUSTER STOP SERVICE; + ~~~ + +1. Drop the ReaderVC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + DROP VIRTUAL CLUSTER ; + ~~~ + +1. On the standby cluster, re-create the ReaderVC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER; + ~~~ + +At this point, the ReaderVC is on the same version as the standby cluster. + +## Failover and fast failback during upgrade + +If you need to, you can still perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. + +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. + +## 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. \ No newline at end of file diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md index caf360faf47..6698490c59c 100644 --- a/src/current/v25.3/upgrade-with-pcr.md +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -5,7 +5,7 @@ toc: true docs_area: manage --- -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. +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. {{site.data.alerts.callout_info}} 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)_. diff --git a/src/current/v25.4/physical-cluster-replication-overview.md b/src/current/v25.4/physical-cluster-replication-overview.md index 65b332607ca..3ec0623a085 100644 --- a/src/current/v25.4/physical-cluster-replication-overview.md +++ b/src/current/v25.4/physical-cluster-replication-overview.md @@ -67,20 +67,6 @@ Statement | Action [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters. [`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. -## Cluster versions and upgrades - -{{site.data.alerts.callout_info}} -The entire standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster. -{{site.data.alerts.end}} - -When PCR is enabled, upgrade with the following procedure. This upgrades the standby cluster before the primary cluster. Within the primary and standby CockroachDB clusters, the system virtual cluster must be at a cluster version greater than or equal to the virtual cluster: - -1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary and standby clusters. Replace the binary on each node of the cluster and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's virtual cluster. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's virtual cluster. - ## Demo video Learn how to use PCR to meet your RTO and RPO requirements with the following demo: diff --git a/src/current/v25.4/upgrade-with-pcr.md b/src/current/v25.4/upgrade-with-pcr.md new file mode 100644 index 00000000000..6698490c59c --- /dev/null +++ b/src/current/v25.4/upgrade-with-pcr.md @@ -0,0 +1,76 @@ +--- +title: Upgrade with Physical Cluster Replication Enabled +summary: Upgrade your primary and standby clusters when using PCR. +toc: true +docs_area: manage +--- + +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. + +{{site.data.alerts.callout_info}} +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)_. +{{site.data.alerts.end}} + +## Upgrade primary and standby clusters + +To upgrade your primary and standby clusters: + +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. + +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. + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. + + {{site.data.alerts.callout_info}} + 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. + {{site.data.alerts.end}} + +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. + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. + + {{site.data.alerts.callout_info}} + 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. + {{site.data.alerts.end}} + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) 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)_]({% 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: + +1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. +1. On the standby cluster, stop the ReaderVC service: + + {% include_cached copy-clipboard.html %} + ~~~ sql + ALTER VIRTUAL CLUSTER STOP SERVICE; + ~~~ + +1. Drop the ReaderVC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + DROP VIRTUAL CLUSTER ; + ~~~ + +1. On the standby cluster, re-create the ReaderVC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER; + ~~~ + +At this point, the ReaderVC is on the same version as the standby cluster. + +## Failover and fast failback during upgrade + +If you need to, you can still perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. + +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. + +## 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. \ No newline at end of file From 7b46171e7e8da07f891d1bbec27094354a4c8077 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Mon, 27 Oct 2025 15:55:36 -0400 Subject: [PATCH 07/13] Removed broken links Removed broken links --- src/current/v24.3/upgrade-with-pcr.md | 2 +- src/current/v25.2/upgrade-with-pcr.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/v24.3/upgrade-with-pcr.md b/src/current/v24.3/upgrade-with-pcr.md index 6698490c59c..952f942cedd 100644 --- a/src/current/v24.3/upgrade-with-pcr.md +++ b/src/current/v24.3/upgrade-with-pcr.md @@ -39,7 +39,7 @@ To upgrade your primary and standby clusters: ## Upgrade ReaderVC -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: +If you have a _reader virtual cluster (ReaderVC)_, 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: 1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the ReaderVC service: diff --git a/src/current/v25.2/upgrade-with-pcr.md b/src/current/v25.2/upgrade-with-pcr.md index 6698490c59c..952f942cedd 100644 --- a/src/current/v25.2/upgrade-with-pcr.md +++ b/src/current/v25.2/upgrade-with-pcr.md @@ -39,7 +39,7 @@ To upgrade your primary and standby clusters: ## Upgrade ReaderVC -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: +If you have a _reader virtual cluster (ReaderVC)_, 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: 1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the ReaderVC service: From 91915b687aab53ab8ff04400cac4309a8687255f Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Mon, 27 Oct 2025 16:32:15 -0400 Subject: [PATCH 08/13] Updated language updated pages to have standardized 'system VC' 'app VC' 'reader VC' language --- src/current/v24.3/upgrade-with-pcr.md | 24 ++++++++++++------------ src/current/v25.2/upgrade-with-pcr.md | 24 ++++++++++++------------ src/current/v25.3/read-from-standby.md | 14 +++++++------- src/current/v25.3/upgrade-with-pcr.md | 24 ++++++++++++------------ src/current/v25.4/read-from-standby.md | 14 +++++++------- src/current/v25.4/upgrade-with-pcr.md | 26 +++++++++++++------------- 6 files changed, 63 insertions(+), 63 deletions(-) diff --git a/src/current/v24.3/upgrade-with-pcr.md b/src/current/v24.3/upgrade-with-pcr.md index 952f942cedd..606426fbb94 100644 --- a/src/current/v24.3/upgrade-with-pcr.md +++ b/src/current/v24.3/upgrade-with-pcr.md @@ -8,7 +8,7 @@ docs_area: manage 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. {{site.data.alerts.callout_info}} -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)_. +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 (system VC)_ must be at a cluster major version greater than or equal to the _application virtual cluster (app VC)_. {{site.data.alerts.end}} ## Upgrade primary and standby clusters @@ -19,7 +19,7 @@ To upgrade your primary and standby clusters: 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. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC. {{site.data.alerts.callout_info}} 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. @@ -27,43 +27,43 @@ To upgrade your primary and standby clusters: 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. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC. {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's AppVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC. - Upgrading the primary cluster's AppVC also upgrades the standby cluster's AppVC, since it replicates from the primary. + Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary. -## Upgrade ReaderVC +## Upgrade reader VC -If you have a _reader virtual cluster (ReaderVC)_, 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: +If you have a _reader virtual cluster (reader VC)_, you must upgrade it independently from the primary and standby clusters, after completing the main upgrade process. Use the following steps to upgrade your reader VC by dropping and re-creating it: -1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. -1. On the standby cluster, stop the ReaderVC service: +1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. +1. On the standby cluster, stop the reader VC service: {% include_cached copy-clipboard.html %} ~~~ sql ALTER VIRTUAL CLUSTER STOP SERVICE; ~~~ -1. Drop the ReaderVC: +1. Drop the reader VC: {% include_cached copy-clipboard.html %} ~~~ sql DROP VIRTUAL CLUSTER ; ~~~ -1. On the standby cluster, re-create the ReaderVC: +1. On the standby cluster, re-create the reader VC: {% include_cached copy-clipboard.html %} ~~~ sql ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER; ~~~ -At this point, the ReaderVC is on the same version as the standby cluster. +At this point, the reader VC is on the same version as the standby cluster. ## Failover and fast failback during upgrade diff --git a/src/current/v25.2/upgrade-with-pcr.md b/src/current/v25.2/upgrade-with-pcr.md index 952f942cedd..606426fbb94 100644 --- a/src/current/v25.2/upgrade-with-pcr.md +++ b/src/current/v25.2/upgrade-with-pcr.md @@ -8,7 +8,7 @@ docs_area: manage 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. {{site.data.alerts.callout_info}} -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)_. +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 (system VC)_ must be at a cluster major version greater than or equal to the _application virtual cluster (app VC)_. {{site.data.alerts.end}} ## Upgrade primary and standby clusters @@ -19,7 +19,7 @@ To upgrade your primary and standby clusters: 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. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC. {{site.data.alerts.callout_info}} 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. @@ -27,43 +27,43 @@ To upgrade your primary and standby clusters: 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. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC. {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's AppVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC. - Upgrading the primary cluster's AppVC also upgrades the standby cluster's AppVC, since it replicates from the primary. + Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary. -## Upgrade ReaderVC +## Upgrade reader VC -If you have a _reader virtual cluster (ReaderVC)_, 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: +If you have a _reader virtual cluster (reader VC)_, you must upgrade it independently from the primary and standby clusters, after completing the main upgrade process. Use the following steps to upgrade your reader VC by dropping and re-creating it: -1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. -1. On the standby cluster, stop the ReaderVC service: +1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. +1. On the standby cluster, stop the reader VC service: {% include_cached copy-clipboard.html %} ~~~ sql ALTER VIRTUAL CLUSTER STOP SERVICE; ~~~ -1. Drop the ReaderVC: +1. Drop the reader VC: {% include_cached copy-clipboard.html %} ~~~ sql DROP VIRTUAL CLUSTER ; ~~~ -1. On the standby cluster, re-create the ReaderVC: +1. On the standby cluster, re-create the reader VC: {% include_cached copy-clipboard.html %} ~~~ sql ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER; ~~~ -At this point, the ReaderVC is on the same version as the standby cluster. +At this point, the reader VC is on the same version as the standby cluster. ## Failover and fast failback during upgrade diff --git a/src/current/v25.3/read-from-standby.md b/src/current/v25.3/read-from-standby.md index 681fa6aa91d..5dca8061812 100644 --- a/src/current/v25.3/read-from-standby.md +++ b/src/current/v25.3/read-from-standby.md @@ -11,13 +11,13 @@ Use this page to understand how the _read from standby_ feature works and how to ## How the read from standby feature works -PCR utilizes [cluster virtualization]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) to separate a cluster's control plane from its data plane. A cluster always has one control plane, called a _system virtual cluster (SystemVC)_, and at least one data plane, called an _App Virtual Cluster (AppVC)_. The standby cluster's SystemVC manages the PCR job and other cluster metadata, and is not used for application queries. All data tables, system tables, and cluster settings in the standby cluster's AppVC are identical to the primary cluster's AppVC. The standby cluster's AppVC itself remains offline during replication. +PCR utilizes [cluster virtualization]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) to separate a cluster's control plane from its data plane. A cluster always has one control plane, called a _system virtual cluster (system VC)_, and at least one data plane, called an _App Virtual Cluster (app VC)_. The standby cluster's system VC manages the PCR job and other cluster metadata, and is not used for application queries. All data tables, system tables, and cluster settings in the standby cluster's app VC are identical to the primary cluster's app VC. The standby cluster's app VC itself remains offline during replication. -When using read from standby, applications can read from the standby cluster, but they do not connect directly to the standby cluster's AppVC. Instead, PCR introduces a _reader virtual cluster (ReaderVC)_. The ReaderVC ensures a clean, isolated environment specifically for serving read queries without interfering with replication or system metadata. It reads continuously from the standby cluster's AppVC using internal pointers, providing access to the replicated data while keeping the AppVC offline. The ReaderVC itself only stores a small amount of metadata and no user data, so it is not expected to take up additional storage space. +When using read from standby, applications can read from the standby cluster, but they do not connect directly to the standby cluster's app VC. Instead, PCR introduces a _reader virtual cluster (reader VC)_. The reader VC ensures a clean, isolated environment specifically for serving read queries without interfering with replication or system metadata. It reads continuously from the standby cluster's app VC using internal pointers, providing access to the replicated data while keeping the app VC offline. The reader VC itself only stores a small amount of metadata and no user data, so it is not expected to take up additional storage space. -The standby cluster's ReaderVC has its own system tables and [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}). The ReaderVC replicates a subset of system tables, including **Users** and **Roles**, from the AppVC, so that existing primary users can authenticate using the same [users and roles]({% link {{ page.version.version }}/security-reference/authorization.md %}) as on the primary cluster's AppVC. Other system tables and cluster settings are set to defaults in the ReaderVC. For more information, consult [Physical Cluster Replication Technical Overview]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}). +The standby cluster's reader VC has its own system tables and [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}). The reader VC replicates a subset of system tables, including **Users** and **Roles**, from the app VC, so that existing primary users can authenticate using the same [users and roles]({% link {{ page.version.version }}/security-reference/authorization.md %}) as on the primary cluster's app VC. Other system tables and cluster settings are set to defaults in the reader VC. For more information, consult [Physical Cluster Replication Technical Overview]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}). -In the event of failover, the ReaderVC's response depends on the type of failover. After failover to the latest timestamp, the ReaderVC continues pointing to the AppVC but stops receiving updates. After failover to a point-in-time timestamp, the ReaderVC is destroyed. +In the event of failover, the reader VC's response depends on the type of failover. After failover to the latest timestamp, the reader VC continues pointing to the app VC but stops receiving updates. After failover to a point-in-time timestamp, the reader VC is destroyed. ## Use the read from standby feature ### Before you begin @@ -46,7 +46,7 @@ ALTER VIRTUAL CLUSTER main SET REPLICATION READ VIRTUAL CLUSTER; ~~~ {{site.data.alerts.callout_info}} -The standby cluster's AppVC must have a status of `replicating` before you can create your ReaderVC. Use the [`SHOW VIRTUAL CLUSTERS`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) command to check the status of the AppVC. +The standby cluster's app VC must have a status of `replicating` before you can create your reader VC. Use the [`SHOW VIRTUAL CLUSTERS`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) command to check the status of the app VC. {{site.data.alerts.end}} ### Check the status of your reader virtual cluster @@ -58,7 +58,7 @@ To confirm that your reader virtual cluster is active: SHOW VIRTUAL CLUSTERS; ~~~ -The output shows a `standby-readonly` virtual cluster in addition to the systemVC and AppVC: +The output shows a `standby-readonly` virtual cluster in addition to the system VC and app VC: ~~~ id | name | data_state | service_mode @@ -69,7 +69,7 @@ The output shows a `standby-readonly` virtual cluster in addition to the systemV ~~~ {{site.data.alerts.callout_info}} -The ReaderVC cannot serve reads until after the PCR initial scan is complete. After completing the initial scan, wait until the ReaderVC's `service_mode` is `shared`, then wait about one minute before connecting to the ReaderVC. +The reader VC cannot serve reads until after the PCR initial scan is complete. After completing the initial scan, wait until the reader VC's `service_mode` is `shared`, then wait about one minute before connecting to the reader VC. {{site.data.alerts.end}} ### Run read-only queries on the standby cluster diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md index 6698490c59c..f6120ce15f9 100644 --- a/src/current/v25.3/upgrade-with-pcr.md +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -8,7 +8,7 @@ docs_area: manage 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. {{site.data.alerts.callout_info}} -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)_. +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 (system VC)_ must be at a cluster major version greater than or equal to the _application virtual cluster (app VC)_. {{site.data.alerts.end}} ## Upgrade primary and standby clusters @@ -19,7 +19,7 @@ To upgrade your primary and standby clusters: 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. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC. {{site.data.alerts.callout_info}} 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. @@ -27,43 +27,43 @@ To upgrade your primary and standby clusters: 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. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC. {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's AppVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC. - Upgrading the primary cluster's AppVC also upgrades the standby cluster's AppVC, since it replicates from the primary. + Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary. -## Upgrade ReaderVC +## Upgrade reader VC -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: +If you have a [_reader virtual cluster (reader VC)_]({% 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 reader VC by dropping and re-creating it: -1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. -1. On the standby cluster, stop the ReaderVC service: +1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. +1. On the standby cluster, stop the reader VC service: {% include_cached copy-clipboard.html %} ~~~ sql ALTER VIRTUAL CLUSTER STOP SERVICE; ~~~ -1. Drop the ReaderVC: +1. Drop the reader VC: {% include_cached copy-clipboard.html %} ~~~ sql DROP VIRTUAL CLUSTER ; ~~~ -1. On the standby cluster, re-create the ReaderVC: +1. On the standby cluster, re-create the reader VC: {% include_cached copy-clipboard.html %} ~~~ sql ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER; ~~~ -At this point, the ReaderVC is on the same version as the standby cluster. +At this point, the reader VC is on the same version as the standby cluster. ## Failover and fast failback during upgrade diff --git a/src/current/v25.4/read-from-standby.md b/src/current/v25.4/read-from-standby.md index b1cd65b77be..ab5f1b7036f 100644 --- a/src/current/v25.4/read-from-standby.md +++ b/src/current/v25.4/read-from-standby.md @@ -11,13 +11,13 @@ Use this page to understand how the _read from standby_ feature works and how to ## How the read from standby feature works -PCR utilizes [cluster virtualization]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) to separate a cluster's control plane from its data plane. A cluster always has one control plane, called a _system virtual cluster (SystemVC)_, and at least one data plane, called an _App Virtual Cluster (AppVC)_. The standby cluster's SystemVC manages the PCR job and other cluster metadata, and is not used for application queries. All data tables, system tables, and cluster settings in the standby cluster's AppVC are identical to the primary cluster's AppVC. The standby cluster's AppVC itself remains offline during replication. +PCR utilizes [cluster virtualization]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) to separate a cluster's control plane from its data plane. A cluster always has one control plane, called a _system virtual cluster (system VC)_, and at least one data plane, called an _App Virtual Cluster (app VC)_. The standby cluster's system VC manages the PCR job and other cluster metadata, and is not used for application queries. All data tables, system tables, and cluster settings in the standby cluster's app VC are identical to the primary cluster's app VC. The standby cluster's app VC itself remains offline during replication. -When using read from standby, applications can read from the standby cluster, but they do not connect directly to the standby cluster's AppVC. Instead, PCR introduces a _reader virtual cluster (ReaderVC)_. The ReaderVC ensures a clean, isolated environment specifically for serving read queries without interfering with replication or system metadata. It reads continuously from the standby cluster's AppVC using internal pointers, providing access to the replicated data while keeping the AppVC offline. The ReaderVC itself only stores a small amount of metadata and no user data, so it is not expected to take up additional storage space. +When using read from standby, applications can read from the standby cluster, but they do not connect directly to the standby cluster's app VC. Instead, PCR introduces a _reader virtual cluster (reader VC)_. The reader VC ensures a clean, isolated environment specifically for serving read queries without interfering with replication or system metadata. It reads continuously from the standby cluster's app VC using internal pointers, providing access to the replicated data while keeping the app VC offline. The reader VC itself only stores a small amount of metadata and no user data, so it is not expected to take up additional storage space. -The standby cluster's ReaderVC has its own system tables and [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}). The ReaderVC replicates a subset of system tables, including **Users** and **Roles**, from the AppVC, so that existing primary users can authenticate using the same [users and roles]({% link {{ page.version.version }}/security-reference/authorization.md %}) as on the primary cluster's AppVC. Other system tables and cluster settings are set to defaults in the ReaderVC. For more information, consult [Physical Cluster Replication Technical Overview]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}). +The standby cluster's reader VC has its own system tables and [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}). The reader VC replicates a subset of system tables, including **Users** and **Roles**, from the app VC, so that existing primary users can authenticate using the same [users and roles]({% link {{ page.version.version }}/security-reference/authorization.md %}) as on the primary cluster's app VC. Other system tables and cluster settings are set to defaults in the reader VC. For more information, consult [Physical Cluster Replication Technical Overview]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}). -In the event of failover, the ReaderVC is destroyed. +In the event of failover, the reader VC is destroyed. ## Use the read from standby feature ### Before you begin @@ -46,7 +46,7 @@ ALTER VIRTUAL CLUSTER main SET REPLICATION READ VIRTUAL CLUSTER; ~~~ {{site.data.alerts.callout_info}} -The standby cluster's AppVC must have a status of `replicating` before you can create your ReaderVC. Use the [`SHOW VIRTUAL CLUSTERS`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) command to check the status of the AppVC. +The standby cluster's app VC must have a status of `replicating` before you can create your reader VC. Use the [`SHOW VIRTUAL CLUSTERS`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) command to check the status of the app VC. {{site.data.alerts.end}} ### Check the status of your reader virtual cluster @@ -58,7 +58,7 @@ To confirm that your reader virtual cluster is active: SHOW VIRTUAL CLUSTERS; ~~~ -The output shows a `standby-readonly` virtual cluster in addition to the systemVC and AppVC: +The output shows a `standby-readonly` virtual cluster in addition to the system VC and app VC: ~~~ id | name | data_state | service_mode @@ -69,7 +69,7 @@ The output shows a `standby-readonly` virtual cluster in addition to the systemV ~~~ {{site.data.alerts.callout_info}} -The ReaderVC cannot serve reads until after the PCR initial scan is complete. After completing the initial scan, wait until the ReaderVC's `service_mode` is `shared`, then wait about one minute before connecting to the ReaderVC. +The reader VC cannot serve reads until after the PCR initial scan is complete. After completing the initial scan, wait until the reader VC's `service_mode` is `shared`, then wait about one minute before connecting to the reader VC. {{site.data.alerts.end}} ### Run read-only queries on the standby cluster diff --git a/src/current/v25.4/upgrade-with-pcr.md b/src/current/v25.4/upgrade-with-pcr.md index 6698490c59c..abee113e667 100644 --- a/src/current/v25.4/upgrade-with-pcr.md +++ b/src/current/v25.4/upgrade-with-pcr.md @@ -8,7 +8,7 @@ docs_area: manage 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. {{site.data.alerts.callout_info}} -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)_. +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 (system VC)_ must be at a cluster major version greater than or equal to the _application virtual cluster (app VC)_. {{site.data.alerts.end}} ## Upgrade primary and standby clusters @@ -19,7 +19,7 @@ To upgrade your primary and standby clusters: 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. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC. {{site.data.alerts.callout_info}} 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. @@ -27,43 +27,43 @@ To upgrade your primary and standby clusters: 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. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC. {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's AppVC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC. - Upgrading the primary cluster's AppVC also upgrades the standby cluster's AppVC, since it replicates from the primary. + Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary. -## Upgrade ReaderVC +## Upgrade reader VC -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: +If you have a [_reader virtual cluster (reader VC)_]({% 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 reader VC by dropping and re-creating it: -1. After upgrading the AppVC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. -1. On the standby cluster, stop the ReaderVC service: +1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. +1. On the standby cluster, stop the reader VC service: {% include_cached copy-clipboard.html %} ~~~ sql ALTER VIRTUAL CLUSTER STOP SERVICE; ~~~ -1. Drop the ReaderVC: +1. Drop the reader VC: {% include_cached copy-clipboard.html %} ~~~ sql DROP VIRTUAL CLUSTER ; ~~~ -1. On the standby cluster, re-create the ReaderVC: +1. On the standby cluster, re-create the reader VC: {% include_cached copy-clipboard.html %} ~~~ sql - ALTER VIRTUAL CLUSTER dest-system SET REPLICATION READ VIRTUAL CLUSTER; + ALTER VIRTUAL CLUSTER SET REPLICATION READ VIRTUAL CLUSTER; ~~~ -At this point, the ReaderVC is on the same version as the standby cluster. +At this point, the reader VC is on the same version as the standby cluster. ## Failover and fast failback during upgrade From 62b74c5685e96333f4bf0dcad23bad61afdfc75d Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Mon, 27 Oct 2025 16:51:44 -0400 Subject: [PATCH 09/13] Docs review changes Changes from docs review- still need to add code snippets --- .../cross-cluster-replication.json | 2 +- .../cross-cluster-replication.json | 2 +- .../cross-cluster-replication.json | 2 +- .../cross-cluster-replication.json | 2 +- src/current/v24.3/upgrade-with-pcr.md | 22 ++++++++++--------- src/current/v25.2/upgrade-with-pcr.md | 22 ++++++++++--------- src/current/v25.3/upgrade-with-pcr.md | 22 ++++++++++--------- src/current/v25.4/upgrade-with-pcr.md | 22 ++++++++++--------- 8 files changed, 52 insertions(+), 44 deletions(-) diff --git a/src/current/_includes/v24.3/sidebar-data/cross-cluster-replication.json b/src/current/_includes/v24.3/sidebar-data/cross-cluster-replication.json index 1167c9e9e42..8b76ae44d8b 100644 --- a/src/current/_includes/v24.3/sidebar-data/cross-cluster-replication.json +++ b/src/current/_includes/v24.3/sidebar-data/cross-cluster-replication.json @@ -47,7 +47,7 @@ ] }, { - "title": "Upgrade with Physical Cluster Replication Enabled", + "title": "Upgrade a Cluster Running PCR", "urls": [ "/${VERSION}/upgrade-with-pcr.html" ] diff --git a/src/current/_includes/v25.2/sidebar-data/cross-cluster-replication.json b/src/current/_includes/v25.2/sidebar-data/cross-cluster-replication.json index 1167c9e9e42..8b76ae44d8b 100644 --- a/src/current/_includes/v25.2/sidebar-data/cross-cluster-replication.json +++ b/src/current/_includes/v25.2/sidebar-data/cross-cluster-replication.json @@ -47,7 +47,7 @@ ] }, { - "title": "Upgrade with Physical Cluster Replication Enabled", + "title": "Upgrade a Cluster Running PCR", "urls": [ "/${VERSION}/upgrade-with-pcr.html" ] diff --git a/src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json b/src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json index d9d997e0b54..d6d9d215952 100644 --- a/src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json +++ b/src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json @@ -47,7 +47,7 @@ ] }, { - "title": "Upgrade with Physical Cluster Replication Enabled", + "title": "Upgrade a Cluster Running PCR", "urls": [ "/${VERSION}/upgrade-with-pcr.html" ] diff --git a/src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json b/src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json index d9d997e0b54..d6d9d215952 100644 --- a/src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json +++ b/src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json @@ -47,7 +47,7 @@ ] }, { - "title": "Upgrade with Physical Cluster Replication Enabled", + "title": "Upgrade a Cluster Running PCR", "urls": [ "/${VERSION}/upgrade-with-pcr.html" ] diff --git a/src/current/v24.3/upgrade-with-pcr.md b/src/current/v24.3/upgrade-with-pcr.md index 606426fbb94..8f44b8e2a9a 100644 --- a/src/current/v24.3/upgrade-with-pcr.md +++ b/src/current/v24.3/upgrade-with-pcr.md @@ -1,21 +1,27 @@ --- -title: Upgrade with Physical Cluster Replication Enabled +title: Upgrade a Cluster Running PCR summary: Upgrade your primary and standby clusters when using PCR. toc: true docs_area: manage --- -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. +To safely perform a major version upgrade on a cluster with [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. You cannot replicate data from a cluster on a newer version to a cluster on an older version. + +This page describes the process for safely performing a major version upgrade on a pair of clusters that have PCR enabled. {{site.data.alerts.callout_info}} 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 (system VC)_ must be at a cluster major version greater than or equal to the _application virtual cluster (app VC)_. {{site.data.alerts.end}} +## 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. + ## Upgrade primary and standby clusters To upgrade your primary and standby clusters: -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. +1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process. 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. @@ -39,7 +45,7 @@ To upgrade your primary and standby clusters: ## Upgrade reader VC -If you have a _reader virtual cluster (reader VC)_, you must upgrade it independently from the primary and standby clusters, after completing the main upgrade process. Use the following steps to upgrade your reader VC by dropping and re-creating it: +If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: 1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the reader VC service: @@ -67,10 +73,6 @@ At this point, the reader VC is on the same version as the standby cluster. ## Failover and fast failback during upgrade -If you need to, you can still perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. - -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. - -## Minor version upgrades +If needed, you can perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/src/current/v25.2/upgrade-with-pcr.md b/src/current/v25.2/upgrade-with-pcr.md index 606426fbb94..8f44b8e2a9a 100644 --- a/src/current/v25.2/upgrade-with-pcr.md +++ b/src/current/v25.2/upgrade-with-pcr.md @@ -1,21 +1,27 @@ --- -title: Upgrade with Physical Cluster Replication Enabled +title: Upgrade a Cluster Running PCR summary: Upgrade your primary and standby clusters when using PCR. toc: true docs_area: manage --- -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. +To safely perform a major version upgrade on a cluster with [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. You cannot replicate data from a cluster on a newer version to a cluster on an older version. + +This page describes the process for safely performing a major version upgrade on a pair of clusters that have PCR enabled. {{site.data.alerts.callout_info}} 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 (system VC)_ must be at a cluster major version greater than or equal to the _application virtual cluster (app VC)_. {{site.data.alerts.end}} +## 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. + ## Upgrade primary and standby clusters To upgrade your primary and standby clusters: -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. +1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process. 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. @@ -39,7 +45,7 @@ To upgrade your primary and standby clusters: ## Upgrade reader VC -If you have a _reader virtual cluster (reader VC)_, you must upgrade it independently from the primary and standby clusters, after completing the main upgrade process. Use the following steps to upgrade your reader VC by dropping and re-creating it: +If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: 1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the reader VC service: @@ -67,10 +73,6 @@ At this point, the reader VC is on the same version as the standby cluster. ## Failover and fast failback during upgrade -If you need to, you can still perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. - -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. - -## Minor version upgrades +If needed, you can perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md index f6120ce15f9..8f44b8e2a9a 100644 --- a/src/current/v25.3/upgrade-with-pcr.md +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -1,21 +1,27 @@ --- -title: Upgrade with Physical Cluster Replication Enabled +title: Upgrade a Cluster Running PCR summary: Upgrade your primary and standby clusters when using PCR. toc: true docs_area: manage --- -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. +To safely perform a major version upgrade on a cluster with [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. You cannot replicate data from a cluster on a newer version to a cluster on an older version. + +This page describes the process for safely performing a major version upgrade on a pair of clusters that have PCR enabled. {{site.data.alerts.callout_info}} 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 (system VC)_ must be at a cluster major version greater than or equal to the _application virtual cluster (app VC)_. {{site.data.alerts.end}} +## 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. + ## Upgrade primary and standby clusters To upgrade your primary and standby clusters: -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. +1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process. 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. @@ -39,7 +45,7 @@ To upgrade your primary and standby clusters: ## Upgrade reader VC -If you have a [_reader virtual cluster (reader VC)_]({% 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 reader VC by dropping and re-creating it: +If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: 1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the reader VC service: @@ -67,10 +73,6 @@ At this point, the reader VC is on the same version as the standby cluster. ## Failover and fast failback during upgrade -If you need to, you can still perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. - -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. - -## Minor version upgrades +If needed, you can perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/src/current/v25.4/upgrade-with-pcr.md b/src/current/v25.4/upgrade-with-pcr.md index abee113e667..48e09919c79 100644 --- a/src/current/v25.4/upgrade-with-pcr.md +++ b/src/current/v25.4/upgrade-with-pcr.md @@ -1,21 +1,27 @@ --- -title: Upgrade with Physical Cluster Replication Enabled +title: Upgrade a Cluster Running PCR summary: Upgrade your primary and standby clusters when using PCR. toc: true docs_area: manage --- -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. +To safely perform a major version upgrade on a cluster with [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. You cannot replicate data from a cluster on a newer version to a cluster on an older version. + +This page describes the process for safely performing a major version upgrade on a pair of clusters that have PCR enabled. {{site.data.alerts.callout_info}} 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 (system VC)_ must be at a cluster major version greater than or equal to the _application virtual cluster (app VC)_. {{site.data.alerts.end}} +## 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. + ## Upgrade primary and standby clusters To upgrade your primary and standby clusters: -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. +1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process. 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. @@ -39,7 +45,7 @@ To upgrade your primary and standby clusters: ## Upgrade reader VC -If you have a [_reader virtual cluster (reader VC)_]({% 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 reader VC by dropping and re-creating it: +If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: 1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the reader VC service: @@ -67,10 +73,6 @@ At this point, the reader VC is on the same version as the standby cluster. ## Failover and fast failback during upgrade -If you need to, you can still perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. - -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. - -## Minor version upgrades +If needed, you can perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters. -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. \ No newline at end of file +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. \ No newline at end of file From 0cf55c91adb9f04d91d6e2eeed235c8497d62439 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 28 Oct 2025 11:44:02 -0400 Subject: [PATCH 10/13] Added code snippets Added code snippets to entire upgrade process --- .../physical-cluster-replication-overview.md | 4 + src/current/v24.3/upgrade-with-pcr.md | 75 +++++++++++++++++-- .../physical-cluster-replication-overview.md | 4 + src/current/v25.2/upgrade-with-pcr.md | 75 +++++++++++++++++-- .../physical-cluster-replication-overview.md | 4 + src/current/v25.3/upgrade-with-pcr.md | 75 +++++++++++++++++-- .../physical-cluster-replication-overview.md | 4 + src/current/v25.4/upgrade-with-pcr.md | 73 ++++++++++++++++-- 8 files changed, 291 insertions(+), 23 deletions(-) diff --git a/src/current/v24.3/physical-cluster-replication-overview.md b/src/current/v24.3/physical-cluster-replication-overview.md index 3188d443053..425bb48b553 100644 --- a/src/current/v24.3/physical-cluster-replication-overview.md +++ b/src/current/v24.3/physical-cluster-replication-overview.md @@ -69,6 +69,10 @@ Statement | Action [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters. [`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. +## Cluster versions and upgrades + +To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). + ## Demo video Learn how to use PCR to meet your RTO and RPO requirements with the following demo: diff --git a/src/current/v24.3/upgrade-with-pcr.md b/src/current/v24.3/upgrade-with-pcr.md index 8f44b8e2a9a..de8448c9038 100644 --- a/src/current/v24.3/upgrade-with-pcr.md +++ b/src/current/v24.3/upgrade-with-pcr.md @@ -23,29 +23,92 @@ To upgrade your primary and standby clusters: 1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process. -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. +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. On each node of the cluster, replace the binary and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC. +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{standby node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -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. +1. Confirm that finalization is complete on the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. On each node of the cluster, replace the binary and restart the node. + +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC. +1. Confirm that finalization is complete on the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary. +1. Confirm that finalization is complete on the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + ## Upgrade reader VC -If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: +If you have a _reader virtual cluster (ReaderVC)_, you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: 1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the reader VC service: diff --git a/src/current/v25.2/physical-cluster-replication-overview.md b/src/current/v25.2/physical-cluster-replication-overview.md index 3ec0623a085..c84d51c7612 100644 --- a/src/current/v25.2/physical-cluster-replication-overview.md +++ b/src/current/v25.2/physical-cluster-replication-overview.md @@ -67,6 +67,10 @@ Statement | Action [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters. [`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. +## Cluster versions and upgrades + +To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). + ## Demo video Learn how to use PCR to meet your RTO and RPO requirements with the following demo: diff --git a/src/current/v25.2/upgrade-with-pcr.md b/src/current/v25.2/upgrade-with-pcr.md index 8f44b8e2a9a..de8448c9038 100644 --- a/src/current/v25.2/upgrade-with-pcr.md +++ b/src/current/v25.2/upgrade-with-pcr.md @@ -23,29 +23,92 @@ To upgrade your primary and standby clusters: 1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process. -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. +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. On each node of the cluster, replace the binary and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC. +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{standby node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -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. +1. Confirm that finalization is complete on the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. On each node of the cluster, replace the binary and restart the node. + +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC. +1. Confirm that finalization is complete on the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary. +1. Confirm that finalization is complete on the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + ## Upgrade reader VC -If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: +If you have a _reader virtual cluster (ReaderVC)_, you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: 1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the reader VC service: diff --git a/src/current/v25.3/physical-cluster-replication-overview.md b/src/current/v25.3/physical-cluster-replication-overview.md index 3ec0623a085..c84d51c7612 100644 --- a/src/current/v25.3/physical-cluster-replication-overview.md +++ b/src/current/v25.3/physical-cluster-replication-overview.md @@ -67,6 +67,10 @@ Statement | Action [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters. [`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. +## Cluster versions and upgrades + +To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). + ## Demo video Learn how to use PCR to meet your RTO and RPO requirements with the following demo: diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md index 8f44b8e2a9a..3e011ddd904 100644 --- a/src/current/v25.3/upgrade-with-pcr.md +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -1,5 +1,5 @@ --- -title: Upgrade a Cluster Running PCR +title: Upgrade with Physical Cluster Replication Enabled summary: Upgrade your primary and standby clusters when using PCR. toc: true docs_area: manage @@ -23,26 +23,89 @@ To upgrade your primary and standby clusters: 1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process. -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. +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. On each node of the cluster, replace the binary and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC. +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{standby node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -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. +1. Confirm that finalization is complete on the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. On each node of the cluster, replace the binary and restart the node. + +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC. +1. Confirm that finalization is complete on the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary. +1. Confirm that finalization is complete on the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + ## Upgrade reader VC If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: diff --git a/src/current/v25.4/physical-cluster-replication-overview.md b/src/current/v25.4/physical-cluster-replication-overview.md index 3ec0623a085..c84d51c7612 100644 --- a/src/current/v25.4/physical-cluster-replication-overview.md +++ b/src/current/v25.4/physical-cluster-replication-overview.md @@ -67,6 +67,10 @@ Statement | Action [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters. [`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. +## Cluster versions and upgrades + +To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). + ## Demo video Learn how to use PCR to meet your RTO and RPO requirements with the following demo: diff --git a/src/current/v25.4/upgrade-with-pcr.md b/src/current/v25.4/upgrade-with-pcr.md index 48e09919c79..fca2d14aa4a 100644 --- a/src/current/v25.4/upgrade-with-pcr.md +++ b/src/current/v25.4/upgrade-with-pcr.md @@ -23,26 +23,89 @@ To upgrade your primary and standby clusters: 1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process. -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. +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. On each node of the cluster, replace the binary and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC. +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{standby node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -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. +1. Confirm that finalization is complete on the standby cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. On each node of the cluster, replace the binary and restart the node. + +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ {{site.data.alerts.callout_info}} 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. {{site.data.alerts.end}} -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC. +1. Confirm that finalization is complete on the primary cluster's system VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + +1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version '{VERSION}'; + ~~~ Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary. +1. Confirm that finalization is complete on the primary cluster's app VC: + + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ + ## Upgrade reader VC If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: From 824bc5afd5ad2a2844cda10b1bbcd4010a482a29 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 28 Oct 2025 11:55:09 -0400 Subject: [PATCH 11/13] Fixed terminology Two instances of readervc didn't get changed --- src/current/v24.3/upgrade-with-pcr.md | 2 +- src/current/v25.2/upgrade-with-pcr.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/v24.3/upgrade-with-pcr.md b/src/current/v24.3/upgrade-with-pcr.md index de8448c9038..e0b01178e61 100644 --- a/src/current/v24.3/upgrade-with-pcr.md +++ b/src/current/v24.3/upgrade-with-pcr.md @@ -108,7 +108,7 @@ To upgrade your primary and standby clusters: ## Upgrade reader VC -If you have a _reader virtual cluster (ReaderVC)_, you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: +If you have a _reader virtual cluster (reader VC)_, you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: 1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the reader VC service: diff --git a/src/current/v25.2/upgrade-with-pcr.md b/src/current/v25.2/upgrade-with-pcr.md index de8448c9038..e0b01178e61 100644 --- a/src/current/v25.2/upgrade-with-pcr.md +++ b/src/current/v25.2/upgrade-with-pcr.md @@ -108,7 +108,7 @@ To upgrade your primary and standby clusters: ## Upgrade reader VC -If you have a _reader virtual cluster (ReaderVC)_, you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: +If you have a _reader virtual cluster (reader VC)_, you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC: 1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed. 1. On the standby cluster, stop the reader VC service: From c129f84025bec0a792cd581b6669978fb03a4a80 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 28 Oct 2025 14:35:18 -0400 Subject: [PATCH 12/13] Final small changes Added some links --- src/current/v24.3/physical-cluster-replication-overview.md | 4 +++- src/current/v24.3/upgrade-cockroach-version.md | 6 +++++- src/current/v24.3/upgrade-with-pcr.md | 2 +- src/current/v25.2/physical-cluster-replication-overview.md | 4 +++- src/current/v25.2/upgrade-cockroach-version.md | 6 +++++- src/current/v25.2/upgrade-with-pcr.md | 2 +- src/current/v25.3/physical-cluster-replication-overview.md | 4 +++- src/current/v25.3/upgrade-cockroach-version.md | 6 +++++- src/current/v25.3/upgrade-with-pcr.md | 2 +- src/current/v25.4/physical-cluster-replication-overview.md | 4 +++- src/current/v25.4/upgrade-cockroach-version.md | 6 +++++- src/current/v25.4/upgrade-with-pcr.md | 2 +- 12 files changed, 36 insertions(+), 12 deletions(-) diff --git a/src/current/v24.3/physical-cluster-replication-overview.md b/src/current/v24.3/physical-cluster-replication-overview.md index 425bb48b553..ef53e26703b 100644 --- a/src/current/v24.3/physical-cluster-replication-overview.md +++ b/src/current/v24.3/physical-cluster-replication-overview.md @@ -71,7 +71,9 @@ Statement | Action ## Cluster versions and upgrades -To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). +To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. + +Follow the process described in [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). ## Demo video diff --git a/src/current/v24.3/upgrade-cockroach-version.md b/src/current/v24.3/upgrade-cockroach-version.md index 99d79b696be..f6a5087f6c2 100644 --- a/src/current/v24.3/upgrade-cockroach-version.md +++ b/src/current/v24.3/upgrade-cockroach-version.md @@ -5,7 +5,11 @@ toc: true docs_area: manage --- -This page describes how major-version and patch upgrades work and shows how to upgrade a self-hosted CockroachDB. To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. +This page describes how major-version and patch upgrades work and shows how to upgrade a self-hosted CockroachDB. + +To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. + +To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link cockroachcloud/upgrade-with-pcr.md %}). ## Overview diff --git a/src/current/v24.3/upgrade-with-pcr.md b/src/current/v24.3/upgrade-with-pcr.md index e0b01178e61..32201d50fa2 100644 --- a/src/current/v24.3/upgrade-with-pcr.md +++ b/src/current/v24.3/upgrade-with-pcr.md @@ -15,7 +15,7 @@ The entire standby cluster must be on the same major version as the primary clus ## 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. +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, so you can follow the normal [patch upgrade process]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-patch-upgrade). ## Upgrade primary and standby clusters diff --git a/src/current/v25.2/physical-cluster-replication-overview.md b/src/current/v25.2/physical-cluster-replication-overview.md index c84d51c7612..9947094fbe3 100644 --- a/src/current/v25.2/physical-cluster-replication-overview.md +++ b/src/current/v25.2/physical-cluster-replication-overview.md @@ -69,7 +69,9 @@ Statement | Action ## Cluster versions and upgrades -To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). +To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. + +Follow the process described in [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). ## Demo video diff --git a/src/current/v25.2/upgrade-cockroach-version.md b/src/current/v25.2/upgrade-cockroach-version.md index 99d79b696be..f6a5087f6c2 100644 --- a/src/current/v25.2/upgrade-cockroach-version.md +++ b/src/current/v25.2/upgrade-cockroach-version.md @@ -5,7 +5,11 @@ toc: true docs_area: manage --- -This page describes how major-version and patch upgrades work and shows how to upgrade a self-hosted CockroachDB. To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. +This page describes how major-version and patch upgrades work and shows how to upgrade a self-hosted CockroachDB. + +To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. + +To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link cockroachcloud/upgrade-with-pcr.md %}). ## Overview diff --git a/src/current/v25.2/upgrade-with-pcr.md b/src/current/v25.2/upgrade-with-pcr.md index e0b01178e61..32201d50fa2 100644 --- a/src/current/v25.2/upgrade-with-pcr.md +++ b/src/current/v25.2/upgrade-with-pcr.md @@ -15,7 +15,7 @@ The entire standby cluster must be on the same major version as the primary clus ## 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. +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, so you can follow the normal [patch upgrade process]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-patch-upgrade). ## Upgrade primary and standby clusters diff --git a/src/current/v25.3/physical-cluster-replication-overview.md b/src/current/v25.3/physical-cluster-replication-overview.md index c84d51c7612..9947094fbe3 100644 --- a/src/current/v25.3/physical-cluster-replication-overview.md +++ b/src/current/v25.3/physical-cluster-replication-overview.md @@ -69,7 +69,9 @@ Statement | Action ## Cluster versions and upgrades -To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). +To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. + +Follow the process described in [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). ## Demo video diff --git a/src/current/v25.3/upgrade-cockroach-version.md b/src/current/v25.3/upgrade-cockroach-version.md index 99d79b696be..f6a5087f6c2 100644 --- a/src/current/v25.3/upgrade-cockroach-version.md +++ b/src/current/v25.3/upgrade-cockroach-version.md @@ -5,7 +5,11 @@ toc: true docs_area: manage --- -This page describes how major-version and patch upgrades work and shows how to upgrade a self-hosted CockroachDB. To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. +This page describes how major-version and patch upgrades work and shows how to upgrade a self-hosted CockroachDB. + +To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. + +To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link cockroachcloud/upgrade-with-pcr.md %}). ## Overview diff --git a/src/current/v25.3/upgrade-with-pcr.md b/src/current/v25.3/upgrade-with-pcr.md index 3e011ddd904..65774013236 100644 --- a/src/current/v25.3/upgrade-with-pcr.md +++ b/src/current/v25.3/upgrade-with-pcr.md @@ -15,7 +15,7 @@ The entire standby cluster must be on the same major version as the primary clus ## 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. +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, so you can follow the normal [patch upgrade process]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-patch-upgrade). ## Upgrade primary and standby clusters diff --git a/src/current/v25.4/physical-cluster-replication-overview.md b/src/current/v25.4/physical-cluster-replication-overview.md index c84d51c7612..9947094fbe3 100644 --- a/src/current/v25.4/physical-cluster-replication-overview.md +++ b/src/current/v25.4/physical-cluster-replication-overview.md @@ -69,7 +69,9 @@ Statement | Action ## Cluster versions and upgrades -To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). +To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. + +Follow the process described in [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). ## Demo video diff --git a/src/current/v25.4/upgrade-cockroach-version.md b/src/current/v25.4/upgrade-cockroach-version.md index 99d79b696be..f6a5087f6c2 100644 --- a/src/current/v25.4/upgrade-cockroach-version.md +++ b/src/current/v25.4/upgrade-cockroach-version.md @@ -5,7 +5,11 @@ toc: true docs_area: manage --- -This page describes how major-version and patch upgrades work and shows how to upgrade a self-hosted CockroachDB. To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. +This page describes how major-version and patch upgrades work and shows how to upgrade a self-hosted CockroachDB. + +To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. + +To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link cockroachcloud/upgrade-with-pcr.md %}). ## Overview diff --git a/src/current/v25.4/upgrade-with-pcr.md b/src/current/v25.4/upgrade-with-pcr.md index fca2d14aa4a..d6f82dfa17d 100644 --- a/src/current/v25.4/upgrade-with-pcr.md +++ b/src/current/v25.4/upgrade-with-pcr.md @@ -15,7 +15,7 @@ The entire standby cluster must be on the same major version as the primary clus ## 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. +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, so you can follow the normal [patch upgrade process]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-patch-upgrade). ## Upgrade primary and standby clusters From 9b38a8ce4e241b8c8cad5f3322ddde3241578c81 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 28 Oct 2025 14:37:35 -0400 Subject: [PATCH 13/13] Broken link whoops broken link --- src/current/v24.3/upgrade-cockroach-version.md | 2 +- src/current/v25.2/upgrade-cockroach-version.md | 2 +- src/current/v25.3/upgrade-cockroach-version.md | 2 +- src/current/v25.4/upgrade-cockroach-version.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/current/v24.3/upgrade-cockroach-version.md b/src/current/v24.3/upgrade-cockroach-version.md index f6a5087f6c2..628ac3ca931 100644 --- a/src/current/v24.3/upgrade-cockroach-version.md +++ b/src/current/v24.3/upgrade-cockroach-version.md @@ -9,7 +9,7 @@ This page describes how major-version and patch upgrades work and shows how to u To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. -To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link cockroachcloud/upgrade-with-pcr.md %}). +To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). ## Overview diff --git a/src/current/v25.2/upgrade-cockroach-version.md b/src/current/v25.2/upgrade-cockroach-version.md index f6a5087f6c2..628ac3ca931 100644 --- a/src/current/v25.2/upgrade-cockroach-version.md +++ b/src/current/v25.2/upgrade-cockroach-version.md @@ -9,7 +9,7 @@ This page describes how major-version and patch upgrades work and shows how to u To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. -To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link cockroachcloud/upgrade-with-pcr.md %}). +To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). ## Overview diff --git a/src/current/v25.3/upgrade-cockroach-version.md b/src/current/v25.3/upgrade-cockroach-version.md index f6a5087f6c2..628ac3ca931 100644 --- a/src/current/v25.3/upgrade-cockroach-version.md +++ b/src/current/v25.3/upgrade-cockroach-version.md @@ -9,7 +9,7 @@ This page describes how major-version and patch upgrades work and shows how to u To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. -To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link cockroachcloud/upgrade-with-pcr.md %}). +To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). ## Overview diff --git a/src/current/v25.4/upgrade-cockroach-version.md b/src/current/v25.4/upgrade-cockroach-version.md index f6a5087f6c2..628ac3ca931 100644 --- a/src/current/v25.4/upgrade-cockroach-version.md +++ b/src/current/v25.4/upgrade-cockroach-version.md @@ -9,7 +9,7 @@ This page describes how major-version and patch upgrades work and shows how to u To upgrade a cluster in CockroachDB {{ site.data.products.cloud }}, refer to [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-cockroach-version.md %}) instead. -To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link cockroachcloud/upgrade-with-pcr.md %}). +To upgrade a cluster with with [physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}), refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}). ## Overview