YugabyteDB Geographic Distribution

YugabyteDB offers several multi-region deployment shapes, and they differ substantially in latency and in what they guarantee.

Placement policy

Replicas are placed according to a cluster-wide policy expressed as cloud, region and zone:

yb-admin --master_addresses <masters> \
  modify_placement_info \
  aws.eu-central-1.eu-central-1a,aws.eu-central-1.eu-central-1b,aws.eu-west-1.eu-west-1a 3

Spreading three replicas across three zones in one region survives a zone failure with local write latency. Spreading across three regions survives a region failure and puts an inter-region round trip on every write.

Geo-partitioning

Rows are pinned to regions by a partition column, using PostgreSQL declarative partitioning with per-partition tablespaces:

CREATE TABLESPACE eu_central WITH (replica_placement =
  '{"num_replicas": 3, "placement_blocks":
     [{"cloud":"aws","region":"eu-central-1","zone":"eu-central-1a","min_num_replicas":1},
      {"cloud":"aws","region":"eu-central-1","zone":"eu-central-1b","min_num_replicas":1},
      {"cloud":"aws","region":"eu-central-1","zone":"eu-central-1c","min_num_replicas":1}]}');
 
CREATE TABLE users (
    id UUID NOT NULL,
    region TEXT NOT NULL,
    email TEXT NOT NULL,
    PRIMARY KEY (id, region)
) PARTITION BY LIST (region);
 
CREATE TABLE users_eu PARTITION OF users
  FOR VALUES IN ('eu') TABLESPACE eu_central;

Each partition's replicas live only in its designated region, which satisfies data residency requirements and gives region-local write latency for that data.

Read replicas

A read replica cluster holds asynchronous copies that do not participate in the Raft quorum, so they add read capacity in a distant region without adding write latency.

SET yb_read_from_followers = true;

Reads from them are stale by an unbounded amount if replication falls behind. Use for content that tolerates staleness, never for read-after-write.

xCluster replication

Asynchronous replication between two separate YugabyteDB clusters, in one direction or bidirectionally.

Choosing a shape