Using Cockroach Demo for Local Testing
The CockroachDB binary ships with a powerful tool for local testing: cockroach demo. This tool creates a local in-memory CockroachDB cluster nearly instantaneously. You can configure it for multiple nodes and regions, run it against built-in workloads like movr, and simulate network latencies for multi-region, global clusters. Because it only requires the cockroach binary, it’s also easy to test different versions of the software. In this post, we’ll look at the basic usage of cockroach demo and follow-up with additional posts on other use cases.
To get started, download the full CockroachDB binary from the CockroachDB Releases page. For this example, I’ll download the latest version of 26.2, which is 26.2.5. I like to organize my binaries locally using ~/crdb/binaries/[version] so I’ll run the following:
1mkdir -p ~/crdb/binaries
2cd ~/crdb/binaries
3wget https://binaries.cockroachdb.com/cockroach-v26.2.5.darwin-11.0-arm64.tgz
4tar -zxf cockroach-v26.2.5.darwin-11.0-arm64.tgz
5mv cockroach-v26.2.5.darwin-11.0-arm64 26.2.5
6rm cockroach-v26.2.5.darwin-11.0-arm64.tgz
7cd 26.2.5
This downloads v26.2.5 for my ARM Mac, extracts it into a versioned directory, and cleans up the archive.
From there, I can run:
1./cockroach demo
2
3#
4# Welcome to the CockroachDB demo database!
5#
6# You are connected to a temporary, in-memory CockroachDB cluster of 1 node.
7#
8# This demo session will send telemetry to Cockroach Labs in the background.
9# To disable this behavior, set the environment variable
10# COCKROACH_SKIP_ENABLING_DIAGNOSTIC_REPORTING=true.
11#
12# Beginning initialization of the movr dataset, please wait...
13#
14# The cluster has been preloaded with the "movr" dataset
15# (MovR is a fictional vehicle sharing company).
16#
17# Reminder: your changes to data stored in the demo session will not be saved!
18#
19# If you wish to access this demo cluster using another tool, you will need
20# the following details:
21#
22# - Connection parameters:
23# (webui) http://127.0.0.1:8080/demologin?password=demo71318&username=demo
24# (cli) cockroach sql --certs-dir=/Users/jonstjohn/.cockroach-demo -u demo -d movr
25# (sql) postgresql://demo:demo71318@127.0.0.1:26257/movr?sslmode=require&sslrootcert=%2FUsers%2Fjonstjohn%2F.cockroach-demo%2Fca.crt
26#
27# - Username: "demo", password: "demo71318"
28# - Directory with certificate files (for certain SQL drivers/tools): /Users/jonstjohn/.cockroach-demo
29#
30# You can enter \info to print these details again.
31#
32# 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)
33# Cluster ID: 5c052011-4bbc-453c-8698-58bb15e9e4c1
34# Organization: Cockroach Demo
35#
36# Enter \? for a brief introduction.
37#
38demo@127.0.0.1:26257/movr>
Every value here — the password, cluster ID, and even the port if 8080/26257 are already in use — is generated fresh each time you run cockroach demo. Yours will look different; don’t expect demo71318 to work on your machine.
This drops me into a SQL shell for the running cluster. If I exit this SQL shell, the demo cluster goes away, so I’ll want to keep it open. I can easily open a second window and connect to it using the instructions in the opening text:
1cockroach sql --certs-dir=/Users/jonstjohn/.cockroach-demo -u demo -d movr
By default, it uses the movr sample database, which already has data in it.
1demo@127.0.0.1:26257/movr> show tables;
2 schema_name | table_name | type | owner | estimated_row_count | locality
3--------------+----------------------------+-------+-------+---------------------+-----------
4 public | promo_codes | table | demo | 1000 | NULL
5 public | rides | table | demo | 500 | NULL
6 public | user_promo_codes | table | demo | 5 | NULL
7 public | users | table | demo | 50 | NULL
8 public | vehicle_location_histories | table | demo | 1000 | NULL
9 public | vehicles | table | demo | 15 | NULL
10(6 rows)
You can interact with the cluster in all the usual ways now, but once you exit the cockroach demo session, the cluster is gone for good.