Skip to content

Added section on multi region behavior #21686

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

Merged
peachdawnleach merged 12 commits into from
Jan 5, 2026
Merged

Added section on multi region behavior #21686

Changes from 4 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
37c2967
Added section on multi region behavior
peachdawnleach Dec 16, 2025
0fd5bcf
Merge branch 'main' into 20251215-doc-15033
peachdawnleach Dec 16, 2025
d65b100
Added links
peachdawnleach Dec 18, 2025
642ca4d
Added clarifying paragraph
peachdawnleach Dec 18, 2025
cd859fd
Removed sentence
peachdawnleach Dec 23, 2025
3ad1188
Changes from docs review
peachdawnleach Dec 29, 2025
d4c38b5
Merge branch 'main' into 20251215-doc-15033
peachdawnleach Dec 29, 2025
32277d1
trigger build
peachdawnleach Dec 30, 2025
8db85f7
Merge branch '20251215-doc-15033' of github.com:cockroachdb/docs into…
peachdawnleach Dec 30, 2025
b5d4a27
trigger build
peachdawnleach Dec 30, 2025
a884ad3
Update set-up-physical-cluster-replication.md
peachdawnleach Jan 5, 2026
33aafc4
Merge branch 'main' into 20251215-doc-15033
peachdawnleach Jan 5, 2026
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
8 changes: 8 additions & 0 deletions src/current/v26.1/physical-cluster-replication-technical-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,11 @@ When a PCR stream is started with a `readonly` virtual cluster, the job will del
After reverting any necessary data, the standby virtual cluster is promoted as available to serve traffic and the replication job ends.

For details on failing back to the primary cluster following a failover, refer to [Fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback).

### Multi-region behavior

You can use PCR to replicate between clusters with different [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions), [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions), and [table localities]({% link {{ page.version.version }}/table-localities.md %}). Mismatched regions and localities do not impact the [failover process]({% link {{ page.version.version }}/failover-replication.md %}) or ability to access clusters after failover, but they do impact [leaseholders]({% link {{ page.version.version }}/architecture/glossary.md %}#leaseholder) and locality-dependent settings. Clusters replicating across different regions may also experience a slight decrease in performance due to longer replication times.
Copy link

@msbutler msbutler Dec 18, 2025

Choose a reason for hiding this comment

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

"they do impact leaseholders and locality-dependent settings"

I think we should be clearer here. If the standby cluster doesn't match the primary's localities, the standby cluster may not be able to satisfy replicating locality constraints. For example, if we're replicating an Regional by Row (rbr) table with partitions in us-east, us-central, and us-west; and the standby cluster does not have any nodes with a locality tag with us-west, the rbr us-west partition constraint cannot be satisfied, and the data will be placed in an arbitrary location on the destination cluster. This arbitrary data placement then has performance implications: if the user was relying on partitioning for intra region latency, we can no longer meet that on the destination.

Copy link
Contributor Author

@peachdawnleach peachdawnleach Dec 18, 2025

Choose a reason for hiding this comment

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

Just added a new paragraph getting a bit more detailed on this

Copy link

@msbutler msbutler Dec 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

nice! one more nit:

Clusters replicating across different regions may also experience a slight decrease in performance due to longer replication times.

IMHO, i think this sentence can be removed, as you explain it more detail in the paragraph below, but perhaps the docs reviewer will have better opinions on how to organize this.


If the localities on the primary cluster do not match the localities on the standby cluster, the standby cluster may be unable to satisfy replicating locality constraints. For example, if a replicated regional by row table has partitions in `us-east`, `us-central`, and `us-west`, and the standby cluster only has nodes with the locality tags `us-east` and `us-central`, the standby cluster cannot satisfy the regional by row `us-west` partition constraint. Data with unsatisfiable partition constraints is placed in an arbitrary location on the standby cluster, which can cause performance issues in the case of a failover event due to latency between regions.
Copy link
Contributor

@jhlodin jhlodin Dec 29, 2025

Choose a reason for hiding this comment

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

The grammar of "regional by row" here is off. Per https://www.cockroachlabs.com/docs/v25.4/table-localities.html it seems like we use both "regional by row" and "REGIONAL BY ROW" interchangeably, but here I would prefer the latter since it reads more neatly as a proper noun. Is there a reason to keep it as-is?

Copy link
Contributor Author

@peachdawnleach peachdawnleach Dec 29, 2025

Choose a reason for hiding this comment

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

I can't think of a reason- changed this


After a failover event involving clusters in different regions, do not change any configurations on your standby cluster if you plan to [fail back to the original primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). If you plan to start using the standby cluster for long-running production traffic rather than performing a failback, adjust the configurations on the standby cluster to optimize for your traffic. When adjusting configurations, ensure that the new settings can be satisfied on the standby cluster. In particular, ensure that the cluster does not have pinned leaseholders for a region that does not exist on the cluster.
Loading