Skip to content

Add page for updated PCR upgrade info #20729

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Add page for updated PCR upgrade info #20729

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6020673
Added pcr upgrade page
peachdawnleach Oct 21, 2025
9071e7d
summary length
peachdawnleach Oct 21, 2025
1d98a00
Merge branch 'main' into 20251014-DOC-14967-reader-vc-upgrade
peachdawnleach Oct 21, 2025
0594686
Quick changes from review
peachdawnleach Oct 22, 2025
8a2903c
More changes from review
peachdawnleach Oct 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
14 changes: 0 additions & 14 deletions src/current/v25.3/physical-cluster-replication-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
80 changes: 80 additions & 0 deletions src/current/v25.3/upgrade-with-pcr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
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 upgrades before the primary cluster.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we say 'That 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)_.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: perhaps link to a page that talks about version skipping etc.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we specify **major ** version?

Also, when you say 'version the primary cluster can directly upgrade to,' i assume you're implying that innovation releases can be skipped? i.e. PCR set up could be going from 25.4 (primary) --> 26.2 (standby), skipping 26.1 which is the primary release? I think we should be explicit, or link to a section of the docs that are explicit about it . Ideally we could just link to docs that are more explicit on it

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version ok found them, we shojld link to these docs

{{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}}

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hm, I'm not super clear what the use case for this is. I'm fine removing this line. I don't know why someone would be in this state


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. Rolling back the upgrade on the primary cluster does not also roll back the standby cluster.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for readability should we say "primary cluster does not roll backup" instead of "does not also"

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

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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more explicit and add somewhere that 'the reader vc must be handled independently' from the upgrade process or something. And then also add a link to this section from the Reader VC page.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^good point. the reader vc should be handled after the main upgrade process.


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 <readervc-name> STOP SERVICE
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: these are SQL statements and should have semicolons at the end, users will often copy and paste

so ALTER VIRTUAL CLUSTER STOP SERVICE; is what it should be

Copy link

@msbutler msbutler Oct 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^imho the sql command should still contain <readervc-name>

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh yeah sorry, that was a copy and paste issue. my main point was we need to add a semicolon at the end of every sql statement code example.

~~~

1. Drop the ReaderVC:

{% include_cached copy-clipboard.html %}
~~~ sql
DROP VIRTUAL CLUSTER <readervc-name>
~~~

1. Back on the standby cluster, if the version is as expected, re-create the ReaderVC:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: remove "back"

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does 'as expected mean?' and what version will the ReaderVC be on once this sql statement is added? will it be the same version as the standby?


{% 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wait what is this normal process referring to? The normal upgrade 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.
Copy link

@alicia-l2 alicia-l2 Oct 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think instead of this, we should say that you cannot perform fast failback under conditions that the standby cluster may be a version ahead of the primary cluster, making it incompatible because we would be replicating data from a cluster that is a version ahead back into a cluster that is a version behind (didn't phrase that very well but the core tenent of version compatibility is that we can't replicate data from a new version into an old version, bc the old versions doesn't know the new version exists)

Then we can list out the conditions:

  • Upgrade process
  • Process where the standby cluster version is higher than the primary

Not super opinionated on the layout, but i think we should be explicit on the version incompatibility issue with fast failback


## 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.
Loading