Cockroach Demo Multiregion Cluster
In a previous post on Using Cockroach Demo for Local Testing, I showed how to easily test different versions of CockroachDB using a local, in-memory cluster. In this post, I look at how easy it is to test multi-region functionality.
To spin up a local cluster with multiple regions, use the --geo-partitioned-replicas flag:
1cockroach demo --geo-partitioned-replicas
which results in this output:
1#
2# --geo-partitioned replicas operates on a 9 node cluster.
3# The cluster size has been changed from the default to 9 nodes.
4#
5# Welcome to the CockroachDB demo database!
6#
7# You are connected to a temporary, in-memory CockroachDB cluster of 9 nodes.
8#
9# This demo session will send telemetry to Cockroach Labs in the background.
10# To disable this behavior, set the environment variable
11# COCKROACH_SKIP_ENABLING_DIAGNOSTIC_REPORTING=true.
12#
13# Beginning initialization of the movr dataset, please wait...
14#
15# Partitioning the demo database, please wait...
16#
17# The cluster has been preloaded with the "movr" dataset
18# (MovR is a fictional vehicle sharing company).
19#
20# Reminder: your changes to data stored in the demo session will not be saved!
21#
22# If you wish to access this demo cluster using another tool, you will need
23# the following details:
24#
25# - Connection parameters:
26# (webui) http://127.0.0.1:8080/demologin?password=demo81017&username=demo
27# (cli) cockroach sql --certs-dir=/Users/jonstjohn/.cockroach-demo -u demo -d movr
28# (sql) postgresql://demo:demo81017@127.0.0.1:26257/movr?sslmode=require&sslrootcert=%2FUsers%2Fjonstjohn%2F.cockroach-demo%2Fca.crt
29#
30# To display connection parameters for other nodes, use \demo ls.
31# - Username: "demo", password: "demo81017"
32# - Directory with certificate files (for certain SQL drivers/tools): /Users/jonstjohn/.cockroach-demo
33#
34# You can enter \info to print these details again.
35#
36# Server version: CockroachDB CCL v26.2.5 (aarch64-apple-darwin21.2, built 2026/07/28 19:18:29, go1.25.5) (same version as client)
37# Cluster ID: a0047ac9-9034-4315-9128-356bf2820007
38# Organization: Cockroach Demo
39#
40# Enter \? for a brief introduction.
41#
42demo@127.0.0.1:26257/movr>
You can inspect the regions with the SHOW REGIONS command:
1show regions;
which produces:
1 region | zones | database_names | primary_region_of | secondary_region_of
2---------------+---------+----------------+-------------------+----------------------
3 europe-west1 | {b,c,d} | {} | {} | {}
4 us-east1 | {b,c,d} | {} | {} | {}
5 us-west1 | {a,b,c} | {} | {} | {}
6(3 rows)
And you can inspect the placement of the nodes with node_id and locality from crdb_internal.gossip_nodes:
1SELECT node_id, locality FROM crdb_internal.gossip_nodes;
which produces:
1 node_id | locality
2----------+---------------------------
3 1 | region=us-east1,az=b
4 2 | region=us-east1,az=c
5 3 | region=us-east1,az=d
6 4 | region=us-west1,az=a
7 5 | region=us-west1,az=b
8 6 | region=us-west1,az=c
9 7 | region=europe-west1,az=b
10 8 | region=europe-west1,az=c
11 9 | region=europe-west1,az=d
12(9 rows)
Now you can create a database using these regions:
1CREATE DATABASE d PRIMARY REGION "us-east1" REGIONS "us-west1", "europe-west1" SURVIVE REGION FAILURE;
And you can switch to using that database:
1USE d;
From there, you can use the multi-region features, such as regional by row tables:
1CREATE TABLE t (k UUID PRIMARY KEY DEFAULT gen_random_uuid(), v STRING) LOCALITY REGIONAL BY ROW;
This makes it easy to test multi-region features.
In addition, cockroach demo can be run with the --global flag to simulate multi-region latencies for the default set of regions:
1cockroach demo --geo-partitioned-replicas --global
which produces:
1#
2# --geo-partitioned replicas operates on a 9 node cluster.
3# The cluster size has been changed from the default to 9 nodes.
4#
5# Welcome to the CockroachDB demo database!
6#
7# You are connected to a temporary, in-memory CockroachDB cluster of 9 nodes.
8# Communication between nodes will simulate real world latencies.
9#
10# WARNING: the use of --global is experimental. Some features may not work as expected.
11...
This isn’t recommended as an approach to performance testing but lets you test multi-region latencies locally.