Testing CockroachDB Super Regions Locally
As discussed in a previous post, cockroach demo is a powerful tool for testing CockroachDB features locally. You can trivially spin up a local multi-region test cluster with cockroach demo --geo-partitioned-replicas, or specify the number of nodes and the specific regions where you want those nodes, which lets you test more advanced features like super regions.
Super regions are a feature in CockroachDB that allows you to constrain replicas to a set of regions. For example, if I have regions across the globe, in North America, the EU and Asia-Pacific, I may want data to stay within those regions. The primary use case is data domiciling, although the feature can also be used to limit the placement of replicas in regions where they may not be needed.
Consider a 9-region cluster with 3 regions in North America, 3 regions in the EU and 3 regions in Asia-Pacific. If I create a cluster then define 3 different super regions corresponding to those areas, I can ensure that data stays in those regions.
I’ll use the following regions, which use the same names as GCP:
| Continent | Region | Location |
|---|---|---|
| North America | us-east1 | South Carolina |
us-central1 | Iowa | |
us-west1 | Oregon | |
| Europe | europe-west1 | Belgium |
europe-west3 | Frankfurt | |
europe-north1 | Finland | |
| Asia-Pacific | asia-east1 | Taiwan |
asia-northeast1 | Tokyo | |
asia-southeast1 | Singapore |
Next, I’ll deploy a local, in-memory cluster using cockroach demo and the --nodes and --demo-locality options.
1cockroach demo --insecure --nodes=9 \
2 --demo-locality=region=us-east1,az=b:region=us-central1,az=a:region=us-west1,az=a:region=europe-west1,az=b:region=europe-west3,az=c:region=europe-north1,az=a:region=asia-east1,az=a:region=asia-northeast1,az=a:region=asia-southeast1,az=a
After the cluster starts and you have a SQL prompt, you can check what regions are available:
1SHOW REGIONS;
which produces:
1 region | zones | database_names | primary_region_of | secondary_region_of
2------------------+-------+----------------+-------------------+----------------------
3 asia-east1 | {a} | {} | {} | {}
4 asia-northeast1 | {a} | {} | {} | {}
5 asia-southeast1 | {a} | {} | {} | {}
6 europe-north1 | {a} | {} | {} | {}
7 europe-west1 | {b} | {} | {} | {}
8 europe-west3 | {c} | {} | {} | {}
9 us-central1 | {a} | {} | {} | {}
10 us-east1 | {b} | {} | {} | {}
11 us-west1 | {a} | {} | {} | {}
12(9 rows)
Now I’ll create a multi-region database with these regions:
1CREATE DATABASE multiregion_demo
2 PRIMARY REGION "us-west1"
3 REGIONS "us-west1", "us-east1", "us-central1",
4 "europe-west1", "europe-west3", "europe-north1",
5 "asia-east1", "asia-northeast1", "asia-southeast1"
6 SURVIVE REGION FAILURE;
Now that I have a multi-region database, I can set up the super regions:
1ALTER DATABASE multiregion_demo ADD SUPER REGION "na" VALUES "us-west1", "us-east1", "us-central1";
2ALTER DATABASE multiregion_demo ADD SUPER REGION "eu" VALUES "europe-west1", "europe-west3", "europe-north1";
3ALTER DATABASE multiregion_demo ADD SUPER REGION "asia" VALUES "asia-east1", "asia-northeast1", "asia-southeast1";
Next, you can view the super regions with the following:
1SHOW SUPER REGIONS FROM DATABASE multiregion_demo;
which produces:
1 database_name | super_region_name | regions
2-------------------+-------------------+-----------------------------------------------
3 multiregion_demo | asia | {asia-east1,asia-northeast1,asia-southeast1}
4 multiregion_demo | eu | {europe-north1,europe-west1,europe-west3}
5 multiregion_demo | na | {us-central1,us-east1,us-west1}
6(3 rows)
You now have a multi-region, local, in-memory database using super regions for testing.