cockroach demo

On this page Carat arrow pointing down
Warning:
As of November 12, 2021, CockroachDB v20.1 is no longer supported. For more details, refer to the Release Support Policy.

The cockroach demo command starts a temporary, in-memory CockroachDB cluster, a preloaded dataset, and opens an interactive SQL shell to the cluster. All SQL shell commands, client-side options, help, and shortcuts supported by the cockroach sql command are also supported by the cockroach demo command.

The in-memory cluster persists only as long as the SQL shell is open. As soon as the shell is exited, the cluster and all its data are permanently destroyed. This command is therefore recommended only as an easy way to experiment with the CockroachDB SQL dialect.

By default, cockroach demo starts in secure mode using TLS certificates to encrypt network communication. It also serves a local Admin UI that does not use TLS encryption.

Each instance of cockroach demo loads a temporary enterprise license that expires after an hour. To prevent the loading of a temporary license, set the --disable-demo-license flag.

Synopsis

Start an in-memory cluster and open an interactive SQL shell:

$ cockroach demo <flags>

Start an in-memory cluster with a preloaded dataset and open an interactive SQL shell:

$ cockroach demo <dataset> <flags>

Start an in-memory cluster in secure mode and open an interactive SQL shell:

$ cockroach demo --insecure=false <other flags>

Execute SQL from the command line against an in-memory cluster:

$ cockroach demo --execute="<sql statement>;<sql statement>" --execute="<sql-statement>" <flags>

Exit the interactive SQL shell and stop the in-memory cluster:

$ \q
ctrl-d

View help:

$ cockroach demo --help

Datasets

Tip:

To start a demo cluster without a pre-loaded dataset, pass the --empty flag.

Workload Description
bank A bank database, with one bank table containing account details.
intro An intro database, with one table, mytable, with a hidden message.
kv A kv database, with one key-value-style table.
movr A movr database, with several tables of data for the MovR example application.

By default, cockroach demo loads the movr database as the current database, with sample region (region) and availability zone (az) replica localities for each node specified with the --nodes flag.
startrek A startrek database, with two tables, episodes and quotes.
tpcc A tpcc database, with a rich schema of multiple tables.
ycsb A ycsb database, with a usertable from the Yahoo! Cloud Serving Benchmark.

Flags

The demo command supports the following general-use flags.

Flag Description
--cache For each demo node, the total size for caches. This can be a percentage (notated as a decimal or with %) or any bytes-based unit, for example:

--cache=.25
--cache=25%
--cache=1000000000 ----> 1000000000 bytes
--cache=1GB ----> 1000000000 bytes
--cache=1GiB ----> 1073741824 bytes

Default: 64MiB
--demo-locality Specify locality information for each demo node. The input is a colon-separated list of key-value pairs, where the ith pair is the locality setting for the ith demo cockroach node.

For example, the following option assigns node 1's region to us-east1 and availability zone to 1, node 2's region to us-east2 and availability zone to 2, and node 3's region to us-east3 and availability zone to 3:

--demo-locality=region=us-east1,az=1:region=us-east1,az=2:region=us-east1,az=3

By default, cockroach demo uses sample region (region) and availability zone (az) replica localities for each node specified with the --nodes flag.
--disable-demo-license New in v20.1: Start the demo cluster without loading a temporary enterprise license that expires after an hour.

Setting the COCKROACH_SKIP_ENABLING_DIAGNOSTIC_REPORTING environment variable will also prevent the loading of a temporary license, along with preventing the sharing of anonymized diagnostic details with Cockroach Labs.
--echo-sql Reveal the SQL statements sent implicitly by the command-line utility. This can also be enabled within the interactive SQL shell via the \set echo shell command.
--empty Start the demo cluster without a pre-loaded dataset.
--execute
-e
Execute SQL statements directly from the command line, without opening a shell. This flag can be set multiple times, and each instance can contain one or more statements separated by semi-colons.

If an error occurs in any statement, the command exits with a non-zero status code and further statements are not executed. The results of each statement are printed to the standard output (see --format for formatting options).
--format How to display table rows printed to the standard output. Possible values: tsv, csv, table, raw, records, sql, html.

Default: table for sessions that output on a terminal; tsv otherwise

This flag corresponds to the display_format client-side option for use in interactive sessions.
--geo-partitioned-replicas Start a 9-node demo cluster with the Geo-Partitioned Replicas topology pattern applied to the movr database.
--insecure Include this to start the demo cluster in insecure mode.

Env Variable: COCKROACH_INSECURE
--max-sql-memory For each demo node, the maximum in-memory storage capacity for temporary SQL data, including prepared queries and intermediate data rows during query execution. This can be a percentage (notated as a decimal or with %) or any bytes-based unit, for example:

--max-sql-memory=.25
--max-sql-memory=25%
--max-sql-memory=10000000000 ----> 1000000000 bytes
--max-sql-memory=1GB ----> 1000000000 bytes
--max-sql-memory=1GiB ----> 1073741824 bytes

Default: 128MiB
--nodes Specify the number of in-memory nodes to create for the demo.

Default: 1
--safe-updates Disallow potentially unsafe SQL statements, including DELETE without a WHERE clause, UPDATE without a WHERE clause, and ALTER TABLE ... DROP COLUMN.

Default: true for interactive sessions; false otherwise

Potentially unsafe SQL statements can also be allowed/disallowed for an entire session via the sql_safe_updates session variable.
--set Set a client-side option before starting the SQL shell or executing SQL statements from the command line via --execute. This flag may be specified multiple times, once per option.

After starting the SQL shell, the \set and unset commands can be use to enable and disable client-side options as well.
--with-load Run a demo movr workload against the preloaded movr database.

New in v20.1: When running a multi-node demo cluster, load is balanced across all nodes.

Logging

By default, the demo command logs errors to stderr.

If you need to troubleshoot this command's behavior, you can change its logging behavior.

Connecting to the demo cluster

When the SQL shell connects to the demo cluster at startup, it prints a welcome text with some tips and cluster details. Most of these details resemble the welcome text that is printed when connecting cockroach sql to a permanent cluster. cockroach demo also includes some URLs to connect to the Admin UI with a web browser, or directly to the cluster with a URL connection parameter across a Unix domain socket connection or a standard TCP connection.

#
# Welcome to the CockroachDB demo database!
#
...
#
# Connection parameters:
#   (console) http://127.0.0.1:53538
#   (sql)     postgres://root:admin@?host=%2Fvar%2Ffolders%2Fpg%2FT%2Fdemo282557495&port=26257
#   (sql/tcp) postgres://root:admin@127.0.0.1:53540?sslmode=require
#
#
# The user "root" with password "admin" has been created. Use it to access the Web UI!
#
...

New in v20.1: To return the client connection URLs for all nodes in a demo cluster from within the SQL shell, use the client-side \demo ls command:

icon/buttons/copy
> \demo ls
node 1:
  (console) http://127.0.0.1:53538
  (sql)     postgres://root:admin@?host=%2Fvar%2Ffolders%2Fpg%2FT%2Fdemo282557495&port=26257
  (sql/tcp) postgres://root:admin@127.0.0.1:53540?sslmode=require

node 2:
  (console) http://127.0.0.1:53783
  (sql)     postgres://root:admin@?host=%2Fvar%2Ffolders%2Fpg%2FT%2Fdemo282557495&port=26258
  (sql/tcp) postgres://root:admin@127.0.0.1:53785?sslmode=require

node 3:
  (console) http://127.0.0.1:53789
  (sql)     postgres://root:admin@?host=%2Fvar%2Ffolders%2Fpg%2FT%2Fdemo282557495&port=26259
  (sql/tcp) postgres://root:admin@127.0.0.1:53791?sslmode=require

...
Note:

The \demo ls command is experimental feature. The interface and output are subject to change.

Admin UI

cockroach demo serves a local Admin UI at the console link. For the duration of the cluster, you can navigate to this link to monitor the cluster's activity in the Admin UI. To login, you can use the root user with password admin.

URL connection parameters

You can connect to the demo cluster using a URL connection parameter (e.g., with the cockroach sql --url command). To establish a Unix domain socket connection with a client that is installed on the same machine, use the sql URL . For standard TCP connections, use the sql/tcp URL.

Note:

You do not need to create or specify node and client certificates in the connection URL to a secure demo cluster.

Diagnostics reporting

By default, cockroach demo shares anonymous usage details with Cockroach Labs. To opt out, set the diagnostics.reporting.enabled cluster setting to false. You can also opt out by setting the COCKROACH_SKIP_ENABLING_DIAGNOSTIC_REPORTING environment variable to false before running cockroach demo.

Shutting down and restarting nodes

New in v20.1: You can shut down and restart individual nodes in a multi-node demo cluster with the \demo SQL shell command.

Warning:

This is an experimental feature. The interface and output are subject to change.

Command Description
\demo shutdown <node number> Shuts down a node.

This command simulates stopping a node that can be restarted. It is similar to cockroach quit.
\demo restart <node number> Restarts a node that has been shut down.
\demo decommission <node number> Decommissions a node.

This command simulates decommissioning a node. It is similar to cockroach quit --decommission.
\demo recommission <node number> Recommissions a decommissioned node.

For examples, see Shut down and restart nodes.

Examples

In these examples, we demonstrate how to start a shell with cockroach demo. For more SQL shell features, see the cockroach sql examples.

Start an interactive SQL shell

icon/buttons/copy
$ cockroach demo
icon/buttons/copy
> CREATE TABLE drivers (
    id UUID DEFAULT gen_random_uuid(),
    city STRING NOT NULL,
    name STRING,
    dl STRING UNIQUE,
    address STRING,
    CONSTRAINT primary_key PRIMARY KEY (city ASC, id ASC)
);
icon/buttons/copy
> INSERT INTO drivers (city, name) VALUES ('new york', 'Catherine Nelson');
icon/buttons/copy
> SELECT * FROM drivers;
                   id                  |   city   |       name       |  dl  | address
+--------------------------------------+----------+------------------+------+---------+
  df3dc272-b572-4ca4-88c8-e9974dbd381a | new york | Catherine Nelson | NULL | NULL
(1 row)
icon/buttons/copy
> \q

Load a sample dataset and start an interactive SQL shell

icon/buttons/copy
$ cockroach demo movr --nodes=3 --demo-locality=region=us-east1:region=us-central1:region=us-west1
icon/buttons/copy
> SHOW TABLES;
          table_name
+----------------------------+
  promo_codes
  rides
  user_promo_codes
  users
  vehicle_location_histories
  vehicles
(6 rows)
icon/buttons/copy
> SELECT * FROM users WHERE city = 'new york';
                   id                  |   city   |       name       |           address           | credit_card
+--------------------------------------+----------+------------------+-----------------------------+-------------+
  00000000-0000-4000-8000-000000000000 | new york | Robert Murphy    | 99176 Anderson Mills        | 8885705228
  051eb851-eb85-4ec0-8000-000000000001 | new york | James Hamilton   | 73488 Sydney Ports Suite 57 | 8340905892
  0a3d70a3-d70a-4d80-8000-000000000002 | new york | Judy White       | 18580 Rosario Ville Apt. 61 | 2597958636
  0f5c28f5-c28f-4c00-8000-000000000003 | new york | Devin Jordan     | 81127 Angela Ferry Apt. 8   | 5614075234
  147ae147-ae14-4b00-8000-000000000004 | new york | Catherine Nelson | 1149 Lee Alley              | 0792553487
(5 rows)
icon/buttons/copy
> \q

Execute SQL from the command-line

icon/buttons/copy
$ cockroach demo \
--execute="CREATE TABLE drivers (
    id UUID DEFAULT gen_random_uuid(),
    city STRING NOT NULL,
    name STRING,
    dl STRING UNIQUE,
    address STRING,
    CONSTRAINT primary_key PRIMARY KEY (city ASC, id ASC)
);" \
--execute="INSERT INTO drivers (city, name) VALUES ('new york', 'Catherine Nelson');" \
--execute="SELECT * FROM drivers;"
CREATE TABLE
INSERT 1
                   id                  |   city   |       name       |  dl  | address
+--------------------------------------+----------+------------------+------+---------+
  df3dc272-b572-4ca4-88c8-e9974dbd381a | new york | Catherine Nelson | NULL | NULL
(1 row)

Run cockroach demo with a workload

icon/buttons/copy
$ cockroach demo --nodes=3 --with-load

This command starts a demo cluster with the movr database preloaded and then inserts rows into each table in the movr database. You can monitor the workload progress on the Admin UI.

New in v20.1: When running a multi-node demo cluster, load is balanced across all nodes.

Start a multi-region demo cluster with automatic geo-partitioning

icon/buttons/copy
$ cockroach demo --geo-partitioned-replicas

This command starts a 9-node demo cluster with the movr database preloaded, and partitions and zone constraints applied to the primary and secondary indexes. For more information, see the Geo-Partitioned Replicas topology pattern.

Shut down and restart nodes

If you start a demo cluster with multiple nodes, you can use the \demo shell command to shut down and restart individual nodes in the demo cluster.

Warning:

This is an experimental feature. The interface and output are subject to change.

For example, if you start a demo cluster with the following command:

icon/buttons/copy
$ cockroach demo --nodes=3

You can shutdown the 3rd node and then restart it:

icon/buttons/copy
> \demo shutdown 3
node 3 has been shutdown
icon/buttons/copy
> \demo restart 3
node 3 has been restarted

You can also decommission the 3rd node and then recommission it:

icon/buttons/copy
> \demo decommission 3
node 3 has been decommissioned
icon/buttons/copy
> \demo recommission 3
node 3 has been recommissioned

Try your own scenario

In addition to using one of the pre-loaded dataset, you can create your own database (e.g., CREATE DATABASE <yourdb>;), or use the empty defaultdb database (e.g., SET DATABASE defaultdb;) to test our your own scenario involving any CockroachDB SQL features you are interested in.

See also


Yes No
On this page

Yes No