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

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

Added section on multi region behavior #21686

Changes from all commits
Commits
Show all changes
4 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
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.

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