Simulate a Multi-Region Cluster on localhost (Insecure)

On this page

New in v21.1: Once you've installed CockroachDB, it's simple to simulate multi-region cluster on your local machine using cockroach demo. This is a useful way to start playing with the improved multi-region abstractions provided by CockroachDB.

Note:

cockroach demo is not suitable for production deployments. Additionally, simulating multiple geographically distributed nodes on a single host is not representative of the performance you should expect of a production deployment. For instructions showing how to do production multi-region deployments, see Orchestrate CockroachDB Across Multiple Kubernetes Clusters and Deploy a Global, Serverless Application. Also be sure to review the Production Checklist.

Before you begin

Make sure you have already installed CockroachDB.

Step 1. Start the cluster

Use the cockroach demo command shown below to start the cluster. This particular combination of flags results in a demo cluster of 9 nodes, with 3 nodes in each region. It sets the appropriate node localities and also simulates the network latency that would occur between nodes in these localities. For more information about each flag, see the cockroach demo documentation, especially for --global.

$ cockroach demo --global --nodes 9 --no-example-database --insecure

When the cluster starts, you'll see a message like the one shown below, followed by a SQL prompt. Note the URLs for:

Viewing the DB Console: http://127.0.0.1:8080.
Connecting to the database from a SQL shell or a programming language: postgres://root@127.0.0.1:26257?sslmode=disable.

#
# Welcome to the CockroachDB demo database!
#
# You are connected to a temporary, in-memory CockroachDB cluster of 9 nodes.
#
# This demo session will attempt to enable enterprise features
# by acquiring a temporary license from Cockroach Labs in the background.
# To disable this behavior, set the environment variable
# COCKROACH_SKIP_ENABLING_DIAGNOSTIC_REPORTING=true.
#
# Reminder: your changes to data stored in the demo session will not be saved!
#
# Connection parameters:
#   (webui)    http://127.0.0.1:8080/demologin?password=demo76950&username=demo
#   (sql)      postgres://demo:demo76950@127.0.0.1:26257?sslmode=require
#   (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26257
#
# To display connection parameters for other nodes, use \demo ls.
#
# The user "demo" with password "demo76950" has been created. Use it to access the Web UI!
#
# Server version: CockroachDB CCL v21.1.2 (x86_64-apple-darwin19, built 2021/06/07 18:13:04, go1.15.11) (same version as client)
# Cluster ID: bfd9fc91-69bd-4417-a2f7-66e556bf2cfd
# Organization: Cockroach Demo
#
# Enter \? for a brief introduction.
#

Step 2. Enter SQL statements at the prompt

Now that your simulated multi-region cluster is running, you are presented with a SQL prompt:

root@127.0.0.1:26257/defaultdb>

You can run some basic CockroachDB SQL statements:

> CREATE DATABASE bank;

> USE bank;

> CREATE TABLE bank.accounts (id INT PRIMARY KEY, balance DECIMAL);

> INSERT INTO bank.accounts VALUES (1, 1000.50);

> SELECT * FROM bank.accounts;

  id | balance
+----+---------+
   1 | 1000.50
(1 row)

Step 3. View cluster health and performance in the DB Console

The DB Console gives you insight into the overall health of your cluster, as well as the performance of any client workloads.

To verify that the 9 nodes you specified are up and running as expected, go to the Cluster Overview at http://localhost:8080/#/overview/list.

Note:

Capacity metrics can be incorrect when running multiple nodes on a single machine. For more details, see this limitation.

To see which nodes are located in which regions, and to see the simulated latencies between them, go to the Network Diagnostics page at http://localhost:8080/#/reports/network/region

To access a variety of time series charts, including graphs of SQL queries and SQL service latency, go to the Metrics page at http://localhost:8080/#/metrics

You may also find the following pages useful:

The Databases page at http://localhost:8080/#/databases shows details about your databases and tables.
The Statements page at http://localhost:8080/#/statements is used to assess the performance of specific queries.
The Jobs page at http://localhost:8080/#/jobs is used to monitor the status of long-running operations like schema changes.

Step 4. Wipe the cluster

When you're done with your demo cluster, you can wipe the cluster by typing the command shown below at the SQL prompt. Note that because this is a temporary, in-memory cluster, this will wipe any data you have added to the cluster. For more information, see the cockroach demo documentation.