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.
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 following
cockroach demo command 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
$ 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:
- Connecting to the database from a SQL shell or a programming language:
# # 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:firstname.lastname@example.org: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:
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
Capacity metrics can be incorrect when running multiple nodes on a single machine. For more details, see this limitation.
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.
- Install the client driver for your preferred language
- Learn more about CockroachDB SQL and the built-in SQL client
- Build an app with CockroachDB
- Further explore CockroachDB capabilities like: