I. Overview

One of the most powerful — and unique — capabilities of CockroachDB is native geo-distribution. Instead of complex replication setups or region-specific database instances, CockroachDB lets you declare data locality as part of your schema. Your database handles the rest.

In this part, we'll explore how multi-region clusters work, the different table locality types, and the latency trade-offs involved.

II. Why Geo-Distribution Matters

For applications with a global user base, the challenge is familiar: data stored in us-east-1 has high latency for users in Southeast Asia or Europe. Traditional solutions involve:

• Running separate database instances per region (complex, hard to keep consistent)

• Caching aggressively (stale data risk)

• Accepting high latency (bad user experience)

CockroachDB offers a fourth option: a single logical database that stores data close to where it's needed, automatically.

III. Setting Up a Multi-Region Cluster

Adding regions to a CockroachDB database is a simple SQL statement:

1ALTER DATABASE myapp ADD REGION "us-east1";
2ALTER DATABASE myapp ADD REGION "europe-west1";
3ALTER DATABASE myapp ADD REGION "asia-southeast1";
4
5-- Set a primary region
6ALTER DATABASE myapp PRIMARY REGION "us-east1";

Each region maps to a set of CockroachDB nodes deployed in that geography. The cluster automatically replicates data according to the locality rules you define.

IV. Table Locality Types

CockroachDB gives you three ways to declare where a table's data should live:

🌍 REGIONAL BY TABLE

All data in the table lives in one specific region. Best for tables with a clear "home" region.

ALTER TABLE configs SET LOCALITY REGIONAL BY TABLE IN "us-east1";

Reads and writes from that region are fast. Other regions pay higher latency.

🌐 GLOBAL

Data is replicated to all regions. Best for read-heavy reference data that needs to be fast everywhere.

ALTER TABLE currencies SET LOCALITY GLOBAL;

Reads are fast from any region. Writes are slower (must achieve global consensus). Use this for data that rarely changes: country lists, currency codes, feature flags.

👤 REGIONAL BY ROW

The most powerful option — each row can belong to a different region. CockroachDB automatically routes each row to its home region.

ALTER TABLE users SET LOCALITY REGIONAL BY ROW;

CockroachDB automatically adds a hidden crdb_region column:

1-- User in Asia
2INSERT INTO users (name, email, crdb_region)
3VALUES ('Nguyen Van A', 'a@example.com', 'asia-southeast1');
4
5-- User in Europe
6INSERT INTO users (name, email, crdb_region)
7VALUES ('Jean Dupont', 'jean@example.com', 'europe-west1');

When a user in Asia reads their own profile, CockroachDB routes the read to the Asia region — low latency. When the US reads that same row, it may pay cross-region latency, but that's expected and acceptable.

V. Latency Trade-offs

Understanding the latency model is crucial for making the right locality decisions:

Rule of thumb:

• User profiles, user-generated content → REGIONAL BY ROW

• Lookup tables, feature flags, config → GLOBAL

• Internal admin data → REGIONAL BY TABLE in your primary region

💡 Key Takeaway: REGIONAL BY ROW is the most powerful feature because it lets your database be smart about where each user's data lives — without any application-level routing logic.

VI. Survival Goals

CockroachDB also lets you declare how your cluster should survive failures:

1-- Survive the loss of any single zone (default)
2ALTER DATABASE myapp SURVIVE ZONE FAILURE;
3
4-- Survive the loss of an entire region
5ALTER DATABASE myapp SURVIVE REGION FAILURE;

Region survival requires at least 3 regions and uses more replicas — which increases storage cost and write latency slightly, but gives you true regional fault tolerance.

VII. Conclusion

Geo-distribution in CockroachDB is a first-class feature built into the SQL layer — not an afterthought or a complex operational setup. With a few ALTER TABLE statements, you can turn a single-region database into a globally distributed system that keeps data close to users.

In Part 6, the final part, we'll look at performance optimization: how to use EXPLAIN ANALYZE, design effective indexes, and avoid common pitfalls when migrating from PostgreSQL.

Thank you for reading! 😊