Multi-region

CockroachDB's multi-region SQL features let users place data — and thereby latency and survivability — explicitly at the database, table, partition, or row level. Implementation spans the SQL catalog, span configuration, the allocator, and CCL helpers.

SQL surface

ALTER DATABASE db PRIMARY REGION "us-east1";
ALTER DATABASE db ADD REGION "us-west1";
ALTER DATABASE db SURVIVE REGION FAILURE;

ALTER TABLE t SET LOCALITY GLOBAL;             -- read everywhere fast
ALTER TABLE t SET LOCALITY REGIONAL BY TABLE IN PRIMARY REGION;
ALTER TABLE t SET LOCALITY REGIONAL BY ROW;     -- rows pinned per-region by region column

Where the code lives

• pkg/sql/alter_database.go, pkg/sql/alter_table_locality.go, pkg/sql/zone_config.go — DDL.
• pkg/sql/catalog/multiregion/ — descriptor enrichment for region enums and locality.
• pkg/ccl/multiregionccl/ — the CCL-licensed planning logic for survivability and ZONE/RBR/RBT.
• pkg/spanconfig/spanconfigsqltranslator/ — turns multi-region descriptors into SpanConfigs.
• pkg/kv/kvserver/allocator/ — replica placement that respects locality constraints.

Region enums

Each multi-region database has an enum type with one value per region. Tables that use REGIONAL BY ROW carry a hidden crdb_region column populated from this enum; the row's location is determined by its region value, which is constrained by foreign-key-like lookups.

Survivability

Two settings:

• SURVIVE ZONE FAILURE (default) — three replicas in the primary region, one per zone.
• SURVIVE REGION FAILURE — at least three regions hold voters; tolerates losing one entire region.

The allocator uses zone-config constraints generated by the multi-region planner to enforce these.

Performance helpers

• LOCALITY GLOBAL is implemented as non_voters plus a future-time read invariant. Reads from any region see a consistent timestamp without crossing the WAN.
• LOCALITY REGIONAL BY ROW partitions a table by region and applies per-region zone configs; a partition prefers reads from its home region.

Related pages

• Span config — translates locality to KV-level constraints.
• KV server — the allocator decides actual placement.
• SQL — DDL surface area.