Geo‑partitioning in YugabyteDB: Requirements, Minimal Design, and Operational Checks

Requirements

Applications often need low‑latency access to data that must stay inside specific geographic regions to satisfy regulatory residency rules or to reduce network latency for users located in those regions. The data‑placement requirement is therefore: store replicas only in the declared regions and avoid unintended cross‑region traffic for normal reads and writes.

Minimal design

YugabyteDB satisfies this requirement with a placement policy attached to a YSQL table. The policy lists the regions (or cloud/zone tuples) where replicas may reside and the desired replica count. The system automatically distributes tablets (shards) across the declared regions, placing leaders and followers according to the Raft consensus group configuration.

Example of creating a table with a two‑region policy (us‑east‑1 and eu‑west‑1):

CREATE TABLE orders (
    order_id   BIGINT PRIMARY KEY,
    customer_id BIGINT,
    order_ts   TIMESTAMPTZ,
    total      NUMERIC(10,2)
) WITH (
    placement = '{
        "num_replicas": 3,
        "placement_blocks": [
            {"cloud": "aws", "region": "us-east-1", "zone": "us-east-1a"},
            {"cloud": "aws", "region": "eu-west-1", "zone": "eu-west-1b"}
        ]
    }'
);

After creation, YugabyteDB spreads each table’s tablets so that every replica lives only inside the two declared regions.

Trust / data boundary

The trust boundary for a geo‑partitioned table is the set of regions enumerated in its placement policy. Data for that table is never written to a node outside those regions during normal operation. Cross‑region traffic occurs only for:

• explicitly requested read‑replicas (e.g., follower reads from a different region),
• backup or periodic compaction traffic that YugabyteDB may route across regions for durability.

Thus, compliance checks can rely on the policy definition as the guarantee of residency.

Operational checks

To verify that the placement policy is being honored, administrators can:

1. List tablet placement with yb-admin:

yb-admin --master_addresses  placement_info --table_name orders

The output shows each tablet’s leader and follower locations; confirm that all entries list only the declared regions.

1. Monitor replica distribution via the Prometheus exporter. Metrics such as ybserver_tablet_leader_count{region="us-east-1"} and ybserver_tablet_follower_count should match the expected counts per region.
2. Set alerts on deviations: if the sum of leaders/followers in a declared region drops below the replica count, fire an alert indicating a possible mis‑placement or node failure.

Failure modes

If a region loses enough nodes to break the Raft quorum for a tablet’s replicas, the tablet becomes unavailable for writes in that region. Because the placement policy does not allow automatic re‑balancing to a new region, the table as a whole may lose write availability until the operator intervenes (e.g., by adding nodes to the failed region or by manually initiating a table‑wide repair). Reads may continue from the surviving region if a quorum remains there, but latency will increase for clients that were previously served by the lost region.

Design‑change triggers

The placement policy is immutable after table creation in YugabyteDB 2.x series. A change is required when:

• A new geographic region is added to the cluster and the business wants the table to also store data there.
• Regulatory residency rules change, mandating inclusion or exclusion of a specific region.
• The workload shifts from write‑heavy to read‑heavy (or vice‑versa) and adjusting replica counts per region would improve cost or performance.

When any of these triggers occur, the operator must:

1. Create a new table with the updated placement policy.
2. Migrate data from the old table to the new one (using yb-admin change‑data‑copy or an ETL process).
3. Switch application traffic to the new table and drop the old one after validation.

Verification steps (conservative)

To confirm the behavior in a test environment:

1. Deploy a YugabyteDB cluster with at least three regions (e.g., us‑east‑1, eu‑west‑1, ap‑south‑1).
2. Create a table with a placement policy covering only two of those regions (as shown above).
3. Insert a modest dataset (e.g., 10 000 rows) using a client located in each region.
4. Run yb-admin placement_info and verify that all tablet leaders and followers are reported only inside the two declared regions.
5. Simulate a region failure by stopping the YB‑TServers in one of the declared regions. Observe that write operations return errors (or become read‑only) while reads from the other declared region continue.
6. After restoring the failed region, attempt to alter the table’s placement policy to add the third region; note the error about immutability. Then create a new table with the updated policy and migrate data to confirm the required workflow.

These steps provide observable evidence that the placement policy enforces the trust boundary, that the failure mode matches expectations, and that policy changes require table recreation.

Limitations and practical checks

• Immutability means any policy change incurs downtime proportional to the data migration time; plan maintenance windows accordingly.
• Storage overhead grows linearly with the number of regions multiplied by the replica count; capacity planning must include this factor.
• Hot spots can arise if a region receives disproportionate traffic; continuously monitor request‑per‑second metrics per region and consider adjusting replica counts or using read‑replicas to balance load.

Regularly run the placement verification command and review Prometheus alerts to catch drift early.