> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# cockroach demo
export const InternalLink = ({version, path = "", children, ...props}) => {
let detectedVersion = version || "stable";
if (typeof window !== 'undefined' && !version) {
const match = window.location.pathname.match(/\/docs\/([^/]+)/);
if (match) {
detectedVersion = match[1];
}
}
const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
return
{children}
;
};
export const version = "v23.2";
The `cockroach demo` command starts a temporary, in-memory CockroachDB cluster of one or more nodes, with or without a preloaded dataset, and opens an interactive SQL shell to the cluster.
* All [SQL shell](#sql-shell) commands, client-side options, help, and shortcuts supported by the `cockroach sql` command are also supported by `cockroach demo`.
* 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 [DB Console](#connection-parameters) that does not use TLS encryption.
* Each instance of `cockroach demo` loads a temporary [Enterprise license](https://www.cockroachlabs.com/get-cockroachdb/enterprise) that expires after 24 hours. To prevent the loading of a temporary license, set the `--disable-demo-license` flag.
* `cockroach demo` opens the SQL shell with a new SQL user named `demo`. The `demo` user is assigned a random password and granted the `admin` role.
`cockroach demo` is designed for testing purposes only. It is not suitable for production deployments. To see a list of recommendations for production deployments, see the Production Checklist.
## Synopsis
View help for `cockroach demo`:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach demo --help
```
Start a single-node demo cluster with the `movr` dataset pre-loaded:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach demo
```
Load a different dataset into a demo cluster:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach demo
```
Run the `movr` workload against a demo cluster:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach demo --with-load
```
Execute SQL from the command line against a demo cluster:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach demo --execute="
```
Start a multi-node demo cluster:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach demo --nodes=
```
Start a multi-region demo cluster with default region and zone localities:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach demo --global --nodes=
```
Stop a demo cluster:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> \q
```
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> quit
```
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> exit
```
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ctrl-d
```
## Datasets
By default, the `movr` dataset is pre-loaded into a demo cluster. To load a different dataset, use [`cockroach demo `](#load-a-sample-dataset-into-a-demo-cluster). To start a demo cluster without a pre-loaded dataset, pass the `--no-example-database` 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
### General
The `demo` command supports the following general-use flags.
| Flag | Description | |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--auto-enable-rangefeeds` | Override the default behavior of `cockroach demo`, which has rangefeeds enabled on startup. If you do not need to use changefeeds with your demo cluster, use `--auto-enable-rangefeeds=false` to disable rangefeeds and improve performance. See Enable rangefeeds for more detail. **Default:**`true` | |
| `--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 *i*th pair is the locality setting for the *i*th 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` | Start the demo cluster without loading a temporary [Enterprise license](https://www.cockroachlabs.com/get-started-cockroachdb) that expires after 24 hours. 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](#commands). | |
| `--embedded` | Minimizes the SQL shell [welcome text](#welcome-text) to be appropriate for embedding in playground-type environments. Specifically, this flag removes details that users in an embedded environment have no control over (e.g., networking information). | |
| `--no-example-database` | Start the demo cluster without a pre-loaded dataset. To obtain this behavior automatically in every new `cockroach demo` session, set the `COCKROACH\_NO\_EXAMPLE\_DATABASE` environment variable to `true`. | |
| | `--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](#client-side-options) for use in interactive sessions. |
| | `--geo-partitioned-replicas` | Start a 9-node demo cluster with geo-partitioning applied to the `movr` database. |
| `--global` | Simulates a multi-region cluster which sets the `--locality` flag on node startup to three different regions. It also simulates the network latency that would occur between them given the specified localities. In order for this to operate as expected, with 3 nodes in each of 3 regions, you must also pass the `--nodes 9` argument. | |
| `--http-port` | Specifies a custom HTTP port to the DB Console for the first node of the demo cluster. In multi-node clusters, the HTTP ports for additional clusters increase from the port of the first node, in increments of 1. For example, if the first node has an HTTP port of `5000`, the second node will have the HTTP port `5001`. | |
| `--insecure` | Include this to start the demo cluster in insecure mode. **Env Variable:**`COCKROACH\_INSECURE` | |
| `--listening-url-file` | The file to which the node's SQL connection URL will be written as soon as the demo cluster is initialized and the node is ready to accept connections. This flag is useful for automation because it allows you to wait until the demo cluster has been initialized so that subsequent commands can connect automatically. | |
| `--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](#client-side-options) 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. | |
| `--sql-port` | Specifies a custom SQL port for the first node of the demo cluster. In multi-node clusters, the SQL ports for additional clusters increase from the port of the first node, in increments of 1. For example, if the first node has the SQL port `3000`, the second node will the SQL port `3001`. | |
| `--with-load` | Run a demo `movr` workload against the preloaded `movr` database. When running a multi-node demo cluster, load is balanced across all nodes. | |
### Logging
By default, the `demo` command does not log messages.
If you need to troubleshoot this command's behavior, you can customize its logging behavior.
## SQL shell
### Welcome text
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 [connection parameters](#connection-parameters) for connecting to the DB Console or for connecting another SQL client to the demo cluster.
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
#
# Welcome to the CockroachDB demo database!
#
# You are connected to a temporary, in-memory CockroachDB cluster of 9 nodes.
#
# Beginning initialization of the movr dataset, please wait...
#
# Waiting for license acquisition to complete...
#
# Partitioning the demo database, please wait...
#
# The cluster has been preloaded with the "movr" dataset
# (MovR is a fictional vehicle sharing company).
#
# Reminder: your changes to data stored in the demo session will not be saved!
#
# If you wish to access this demo cluster using another tool, you will need
# the following details:
#
# - Connection parameters:
# (webui) http://127.0.0.1:8080/demologin?password=demo55826&username=demo
# (sql) postgresql://demo:demo55826@127.0.0.1:26257/movr?sslmode=require
# (sql/jdbc) jdbc:postgresql://127.0.0.1:26257/movr?password=demo55826&sslmode=require&user=demo
# (sql/unix) postgresql://demo:demo55826@/movr?host=%2Fvar%2Ffolders%2F8c%2F915dtgrx5_57bvc5tq4kpvqr0000gn%2FT%2Fdemo699845497&port=26257
#
# To display connection parameters for other nodes, use \demo ls.
# - Username: "demo", password: "demo55826"
# - Directory with certificate files (for certain SQL drivers/tools): /var/folders/8c/915dtgrx5_57bvc5tq4kpvqr0000gn/T/demo699845497
#
# Server version: CockroachDB CCL v23.2.29 (x86_64-apple-darwin20.5.0, built 2026-02-19 00:00:00) (same version as client)
# Cluster ID: f78b7feb-b6cf-4396-9d7f-494982d7d81e
# Organization: Cockroach Demo
#
# Enter \? for a brief introduction.
#
```
### Connection parameters
The SQL shell welcome text includes connection parameters for accessing the DB Console and for connecting other SQL clients to the demo cluster:
```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
# - Connection parameters:
# (webui) http://127.0.0.1:8080/demologin?password=demo55826&username=demo
# (sql) postgresql://demo:demo55826@127.0.0.1:26257/movr?sslmode=require
# (sql/jdbc) jdbc:postgresql://127.0.0.1:26257/movr?password=demo55826&sslmode=require&user=demo
# (sql/unix) postgresql://demo:demo55826@/movr?host=%2Fvar%2Ffolders%2F8c%2F915dtgrx5_57bvc5tq4kpvqr0000gn%2FT%2Fdemo699845497&port=26257
```
| Parameter | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `webui` | Use this link to access a local DB Console to the demo cluster. |
| `sql` | Use this connection URL for standard sql/tcp connections from other SQL clients such as `cockroach sql`. The default SQL port for the first node of a demo cluster is `26257`. |
| `sql/unix` | Use this connection URL to establish a Unix domain socket connection with a client that is installed on the same machine. |
You do not need to create or specify node and client certificates in `sql` or `sql/unix` connection URLs. Instead, you can securely connect to the demo cluster with the random password generated for the `demo` user.
When running a multi-node demo cluster, use the `\demo ls` [shell command](#commands) to list the connection parameters for all nodes:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> \demo ls
```
```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
node 1:
(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
node 2:
(webui) http://127.0.0.1:8081/demologin?password=demo76950&username=demo
(sql) postgres://demo:demo76950@127.0.0.1:26258?sslmode=require
(sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26258
node 3:
(webui) http://127.0.0.1:8082/demologin?password=demo76950&username=demo
(sql) postgres://demo:demo76950@127.0.0.1:26259?sslmode=require
(sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26259
```
### Commands
* [General](#general)
* [Demo-specific](#demo-specific)
#### General
The following commands can be used within the interactive SQL shell:
| Command | Usage |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `\?`,`help` | View this help within the shell. |
| `\q`,`quit`,`exit`,`ctrl-d` | Exit the shell. When no text follows the prompt, `ctrl-c` exits the shell as well; otherwise, `ctrl-c` clears the line. |
| `\!` | Run an external command and print its results to `stdout`. See an example. |
| `\|` | Run the output of an external command as SQL statements. See an example. |
| `\set `,`\unset ` | Enable or disable a client-side option. For more details, see [Client-side options](#client-side-options). You can also use the [`--set` flag](#general) to enable or disable client-side options before starting the SQL shell. |
| `\p`,`\show` | During a multi-line statement or transaction, show the SQL that has been entered but not yet executed. `\show` was deprecated as of v21.1. Use `\p` instead. |
| `\h `,`\hf ` | View help for specific SQL statements or functions. See [SQL shell help](#help) for more details. |
| `\c `,`\connect ` | Display or change the current connection parameters. Using `\c` without an argument lists the current connection parameters. To reuse the existing connection and change the current database, use `\c `. This is equivalent to `SET ` and `USE `. To connect to a cluster using individual connection parameters, use `\c `. Use the dash character (`-`) to omit one parameter. To reconnect to the cluster using the current connection parameters enter `\c -`. When using individual connection parameters, the TLS settings from the original connection are reused. To use different TLS settings, connect using a connection URL. To connect to a cluster using a connection URL use `\c ` |
| `\l` | List all databases in the CockroachDB cluster. This command is equivalent to `SHOW DATABASES`. |
| `\d[S+] []` | Show details about the relations in the current database. By default this command will show all the user tables, indexes, views, materialized views, and sequences in the current database. Add the `S` modifier to also show all system objects. If you specify a relation or a [pattern](#patterns), it will show the details of matching relations. Add the `+` modifier to show additional information. |
| `\dC[+] []` | Show the type casts. If you specify a type or a [pattern](#patterns), it will show the details of matching types. Add the `+` modifier to show additional information. |
| `\dd[S] []` | Show the objects of type `constraint` in the current database. Add the `S` modifier to also show all system objects. If you specify a type or a [pattern](#patterns), it will show the details of matching objects. |
| `\df[S+] []` | Show the user-defined functions of the current database. Add the `S` modifier to also show all system functions. If you specify a function name or a [pattern](#patterns), it will show the details of matching function. Add the `+` modifier to show additional information. |
| `\dg[S+] []` | Show the roles of the current database. Add the `S` modifier to also show all system objects. If you specify a role name or a [pattern](#patterns), it will show the details of matching roles. Add the `+` modifier to show additional information. |
| `\di[S+] []` | Show the indexes of the current database. Add the `S` modifier to also show all system objects. If you specify an index name or a [pattern](#patterns), it will show the details of matching indexes. Add the `+` modifier to show additional information. |
| `\dm[S+] []` | Show the materialized views of the current database. Add the `S` modifier to also show all system objects. If you specify a materialized view name or a [pattern](#patterns), it will show the details of matching materialized views. Add the `+` modifier to show additional information. |
| `\dn[S+] []` | List all schemas in the current database. Add the `S` modifier to also show all system schemas. Add the `+` modifier to show the permissions of each schema. Specify a [pattern](#patterns) to limit the output to schemas that match the pattern. These commands are equivalent to `SHOW SCHEMAS`. |
| `\ds[S+] []` | Show the sequences of the current database. Add the `S` modifier to also show all system objects. If you specify a sequence name or a [pattern](#patterns), it will show the details of matching sequences. Add the `+` modifier to show additional information. |
| `\dt[S+] []` | Show the tables of the current database. Add the `S` modifier to also show all system objects. If you specify a table name or a [pattern](#patterns), it will show the details of matching tables. Add the `+` modifier to show additional information. |
| `\dT[S+] []` | Show the user-defined types in the current database. Add the `S` modifier to also show all system objects. If you specify a type name or a [pattern](#patterns), it will show the details of matching types. Add the `+` modifier to show additional information. |
| `\du[S+] []` | Show the roles of the current database. Add the `S` modifier to also show all system objects. If you specify a role name or a [pattern](#patterns), it will show the details of matching roles. Add the `+` modifier to show additional information. |
| `\dv[S+] []` | Show the views of the current database. Add the `S` modifier to also show all system objects. If you specify a view name or a [pattern](#patterns), it will show the details of matching views. Add the `+` modifier to show additional information. |
| `\r` | Resets the query input buffer, clearing all SQL statements that have been entered but not yet executed. |
| `\statement-diag list` | List available diagnostic bundles. |
| `\statement-diag download []` | Download diagnostic bundle. |
| `\i ` | Reads and executes input from the file \`\`, in the current working directory. |
| `\ir ` | Reads and executes input from the file ``. When invoked in the interactive shell, `\i` and `\ir` behave identically (i.e., CockroachDB looks for `` in the current working directory). When invoked from a script, CockroachDB looks for \`\` relative to the directory in which the script is located. |
| `\echo ` | Evaluate the \`\` and print the results to the standard output. |
| `\x ` | When `true`/`on`/`yes`/`1`, sets the display format to `records`. When `false`/`off`/`no`/`0`, sets the session's format to the default (`table`/`tsv`). |
#### Patterns
Commands use the SQL `LIKE` syntax for string pattern matching, not POSIX regular expressions.
For example to list all schemas that begin with the letter "p" you'd use the following pattern:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
\dn p%
```
```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
List of schemas:
Name | Owner
---------------+--------
pg_catalog | NULL
pg_extension | NULL
public | admin
(3 rows)
```
#### Demo-specific
`cockroach demo` offers the following additional shell commands. Note that these commands are **experimental** and their interface and output are subject to change.
| Command | Usage |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `\demo ls` | List the demo nodes and their connection URLs. |
| `\demo add region=,zone=` | Add a node to a single-region or multi-region demo cluster. [See an example](#add-shut-down-and-restart-nodes-in-a-multi-node-demo-cluster). |
| `\demo shutdown ` | Shuts down a node in a multi-node demo cluster. This command simulates stopping a node that can be restarted. [See an example](#add-shut-down-and-restart-nodes-in-a-multi-node-demo-cluster). |
| `\demo restart ` | Restarts a node in a multi-node demo cluster. [See an example](#add-shut-down-and-restart-nodes-in-a-multi-node-demo-cluster). |
| `\demo decommission ` | Decommissions a node in a multi-node demo cluster. This command simulates decommissioning a node. |
| `\demo recommission ` | Recommissions a decommissioned node in a multi-node demo cluster. |
### Client-side options
* To view option descriptions and how they are currently set, use `\set` without any options.
* To enable or disable an option, use `\set