A multi-region TiDB cluster with missing labels fails quietly. The Placement Driver (PD) cannot tell two TiKV nodes in the same zone from two in different regions, so it can place a majority of a Region’s replicas in one zone, and a single zone outage takes that data offline. This guide walks through TiDB multi-region deployment configuration in the order that prevents that failure.
How Do You Configure a Multi-Region TiDB Deployment?
Configure a multi-region TiDB deployment in three steps. Label every TiKV node with its region, zone, and host, tell PD which labels define the topology with location-labels, then use placement rules to control replica count and leader location. Labels describe where each node sits, and placement rules decide where each piece of data goes.
- Label every TiKV node. In the TiUP topology file, set
server.labelson each TiKV instance. Include aregionlabel if you plan to use placement policies, becausePRIMARY_REGIONandREGIONSmatch on that key. - Tell PD how to read the labels.
location-labelslists label keys from broadest to narrowest.isolation-levelsets the minimum level at which PD must separate replicas. - Verify the labels. Run
SHOW PLACEMENT LABELSto confirm TiDB sees every region before you create any policy.
server_configs:
pd:
replication.location-labels: ["region", "zone", "host"]
replication.isolation-level: "zone"
replication.max-replicas: 5
tikv_servers:
- host: 10.0.1.11
config:
server.labels: { region: "us-east-1", zone: "us-east-1a", host: "tikv-1" }
- host: 10.0.1.12
config:
server.labels: { region: "us-east-1", zone: "us-east-1b", host: "tikv-2" }
- host: 10.0.2.11
config:
server.labels: { region: "us-west-1", zone: "us-west-1a", host: "tikv-3" }With isolation-level set to zone, PD refuses to place two replicas of the same Region in one zone, even if that leaves a replica unscheduled. The multi-data-center deployment documentation covers full topology files for each layout.
How TiDB Labels and Placement Rules Control Where Data Lands
Labels make PD aware of topology. Placement Rules in SQL turn that awareness into guarantees about where specific data lives, which is what compliance and latency requirements demand.
-- Five replicas across two US regions, leaders in us-east-1
CREATE PLACEMENT POLICY us_primary
PRIMARY_REGION="us-east-1"
REGIONS="us-east-1,us-west-1"
FOLLOWERS=4;
-- Three replicas, EU regions only
CREATE PLACEMENT POLICY eu_only
PRIMARY_REGION="eu-west-1"
REGIONS="eu-west-1,eu-central-1"
FOLLOWERS=2;
ALTER TABLE orders PLACEMENT POLICY=us_primary;
ALTER TABLE eu_customers PLACEMENT POLICY=eu_only;PRIMARY_REGION sets where Raft leaders live, so writes commit there. REGIONS limits where any replica can land, and FOLLOWERS sets the replica count beyond the leader. Policies also attach to partitions, so a table partitioned by country can keep each partition in its own jurisdiction.
Two rules prevent surprises. ALTER PLACEMENT POLICY replaces the full definition rather than merging it, so restate every option when you change one. Placement policies are also not available on TiDB Cloud Starter or Essential clusters.
How to Monitor and Maintain a Multi-Region TiDB Cluster
Monitor a multi-region cluster at two levels: whether data sits where the policies say, and whether the cluster performs within its latency targets. SHOW PLACEMENT reports the scheduling state of every policy-bound object. A table stuck in PENDING signals that PD cannot satisfy its rule, for example because a region lacks enough labeled TiKV nodes.
For performance, TiUP deploys Prometheus and Grafana alongside the cluster. The PD dashboard’s Region health panel shows Regions with missing or extra replicas, an early sign of a labeling or capacity problem. Add TiKV nodes in a region before you tighten a policy that needs them, update labels whenever hardware moves, and rehearse a zone failure before going live.
Get labels right and the rest of a multi-region TiDB deployment follows. PD spreads replicas safely, and placement policies put each table’s data and leaders where compliance and latency require.
Start building for free. Spin up a TiDB Cloud Starter cluster to build and test your schema at no cost, then apply these placement policies when you deploy on TiDB Self-Managed or TiDB Cloud Dedicated.
Frequently Asked Questions About Multi-Region TiDB Deployment
What are TiDB labels and why do they matter for multi-region deployments?
Labels are key-value tags, such as region, zone, and host, that you attach to each TiKV node to describe its physical location. PD reads them through the location-labels setting and uses them to spread the replicas of each data Region across failure domains. Without labels, PD cannot tell whether two nodes share a zone, so it can place a majority of replicas where one outage removes them. Placement policies also depend on labels to find regions.
How many replicas should each region have?
Match the replica layout to the failure you must survive. Three replicas across three zones in one region protect against a zone outage and keep write latency low. To survive the loss of an entire region, run five replicas split 2-2-1 across three regions, so losing any single region still leaves a three-replica majority. In placement policy terms, FOLLOWERS=2 gives three replicas and FOLLOWERS=4 gives five.
What is the difference between this guide and TiDB’s geo-distributed systems guide?
This guide covers configuration mechanics: labels, PD settings, and placement policies, in the order you apply them. TiDB’s geo-distributed systems guide covers the latency and consistency tradeoffs that decide which topology to choose Read that guide to pick a design, and use this one to configure it.
Does multi-region deployment require downtime to set up?
No full outage is required. TiUP applies TiKV label changes through a rolling restart, one node at a time, and moves Raft leaders off each node before it restarts, so the cluster keeps serving traffic. Placement policies apply online. After ALTER TABLE assigns a policy, PD moves replicas and leaders in the background, and SHOW PLACEMENT reports progress until scheduling completes.