On this page 
New in v2.1: CockroachDB comes with built-in load generators for simulating different types of client workloads, printing out per-operation statistics every second and totals after a specific duration or max number of operations. To run one of these load generators, use the cockroach workload command as described below.
Warning:
The cockroach workload command is experimental. The interface and output are subject to change.
Synopsis
# Create the schema for a workload:
$ cockroach workload init <workload> <flags> '<connection string>'
# Run a workload:
$ cockroach workload run <workload> <flags> '<connection string>'
# View help:
$ cockroach workload --help
$ cockroach workload init --help
$ cockroach workload init <workload> --help
$ cockroach workload run --help
$ cockroach workload run <workload> --help
Subcommands
| Command | Usage |
|---|---|
init |
Load the schema for the workload. You run this command once for a given schema. |
run |
Run a workload. You can run this command multiple times from different machines to increase concurrency. See Concurrency for more details. |
Concurrency
There are two ways to increase the concurrency of a workload:
- Increase the concurrency of a single workload instance by running
cockroach workload run <workload>with the--concurrencyflag set to a value higher than the default. - Run multiple instances of a workload in parallel by running
cockroach workload run <workload>multiple times from different machines.
Workloads
| Workload | Description |
|---|---|
bank |
Models a set of accounts with currency balances. For this workload, you run workload init to load the schema and then workload run to generate data. |
intro |
Loads an intro database, with one table, mytable, with a hidden message.For this workload, you run only workload init to load the data. The workload run subcommand is not applicable. |
kv |
Reads and writes to keys spread (by default, uniformly at random) across the cluster. For this workload, you run workload init to load the schema and then workload run to generate data. |
startrek |
Loads a startrek database, with two tables, episodes and quotes.For this workload, you run only workload init to load the data. The workload run subcommand is not applicable. |
tpcc |
Simulates a transaction processing workload using a rich schema of multiple tables. For this workload, you run workload init to load the schema and then workload run to generate data. |
Flags
Note:
The cockroach workload command does not support connection or security flags like other cockroach commands. Instead, you must use a connection string at the end of the command.
bank workload
| Flag | Description |
|---|---|
--concurrency |
The number of concurrent workers. Applicable commands: init or runDefault: 8 |
--db |
The SQL database to use. Applicable commands: init or runDefault: bank |
--drop |
Drop the existing database, if it exists. Applicable commands: init or run. For the run command, this flag must be used in conjunction with --init. |
--duration |
The duration to run, with a required time unit suffix. Valid time units are ns, us, ms, s, m, and h.Applicable commands: init or runDefault: 0, which means run forever. |
--histograms |
The file to write per-op incremental and cumulative histogram data to. Applicable command: run |
--init |
Automatically run the init command.Applicable command: run |
--max-ops |
The maximum number of operations to run. Applicable command: run |
--max-rate |
The maximum frequency of operations (reads/writes). Applicable command: runDefault: 0, which means unlimited. |
--payload-bytes |
The size of the payload field in each initial row. Applicable commands: init or runDefault: 100 |
--ramp |
The duration over which to ramp up load. Applicable command: run |
--ranges |
The initial number of ranges in the bank table.Applicable commands: init or runDefault: 10 |
--rows |
The initial number of accounts in the bank table.Applicable commands: init or runDefault: 1000 |
--seed |
The key hash seed. Applicable commands: init or runDefault: 1 |
--tolerate-errors |
Keep running on error. Applicable command: run |
intro and startrek workloads
Note:
These workloads generate data but do not offer the ability to run continuous load. Thus, only the init subcommand is supported.
| Flag | Description |
|---|---|
--drop |
Drop the existing database, if it exists, before loading the dataset. |
kv workload
| Flag | Description |
|---|---|
--batch |
The number of blocks to insert in a single SQL statement. Applicable commands: init or runDefault: 1 |
--concurrency |
The number of concurrent workers. Applicable commands: init or runDefault: 8 --cycle-length |
--db |
The SQL database to use. Applicable commands: init or runDefault: kv |
--drop |
Drop the existing database, if it exists. Applicable commands: init or run |
--duration |
The duration to run, with a required time unit suffix. Valid time units are ns, us, ms, s, m, and h.Applicable command: runDefault: 0, which means run forever. |
--histograms |
The file to write per-op incremental and cumulative histogram data to. Applicable command: run |
--init |
Automatically run the init command.Applicable command: run |
--max-block-bytes |
The maximum amount of raw data written with each insertion. Applicable commands: init or runDefault: 2 |
--max-ops |
The maximum number of operations to run. Applicable command: run |
--max-rate |
The maximum frequency of operations (reads/writes). Applicable command: runDefault: 0, which means unlimited. |
--min-block-bytes |
The minimum amount of raw data written with each insertion. Applicable commands: init or runDefault: 1 |
--ramp |
The duration over which to ramp up load. Applicable command: run |
--read-percent |
The percent (0-100) of operations that are reads of existing keys. Applicable commands: init or run |
--seed |
The key hash seed. Applicable commands: init or runDefault: 1 |
--sequential |
Pick keys sequentially instead of randomly. Applicable commands: init or run |
--splits |
The number of splits to perform before starting normal operations. Applicable commands: init or run |
--tolerate-errors |
Keep running on error. Applicable command: run |
--use-opt |
Use cost-based optimizer. Applicable commands: init or runDefault: true |
--write-seq |
Initial write sequence value. Applicable commands: init or run |
tpcc workload
| Flag | Description |
|---|---|
--active-warehouses |
Run the load generator against a specific number of warehouses. Applicable commands: init or runDefaults: Value of --warehouses |
--db |
The SQL database to use. Applicable commands: init or runDefault: tpcc |
--drop |
Drop the existing database, if it exists. Applicable commands: init or run. For the run command, this flag must be used in conjunction with --init. |
--duration |
The duration to run, with a required time unit suffix. Valid time units are ns, us, ms, s, m, and h.Applicable command: runDefault: 0, which means run forever. |
--fks |
Add foreign keys. Applicable commands: init or runDefault: true |
--histograms |
The file to write per-op incremental and cumulative histogram data to. Applicable command: run |
--init |
Automatically run the init command.Applicable command: run |
--interleaved |
Use interleaved tables. Applicable commands: init or run |
--max-ops |
The maximum number of operations to run. Applicable command: run |
--max-rate |
The maximum frequency of operations (reads/writes). Applicable command: runDefault: 0, which means unlimited. |
--mix |
Weights for the transaction mix. Applicable commands: init or runDefault: newOrder=10,payment=10,orderStatus=1,delivery=1,stockLevel=1, which matches the TPC-C specification. |
--partition-affinity |
Run the load generator against a specific partition. This flag must be used in conjunction with --partitions.Applicable commands: init or runDefault: -1 |
--partitions |
Partition tables. This flag must be used in conjunction with --split.Applicable commands: init or run |
--ramp |
The duration over which to ramp up load. Applicable command: run |
--scatter |
Scatter ranges. Applicable commands: init or run |
--seed |
The random number generator seed. Applicable commands: init or runDefault: 1 |
--serializable |
Force serializable mode. CockroachDB only supports SERIALIZABLE isolation, so this flag is not necessary.Applicable command: init |
--split |
Split tables. Applicable commands: init or run |
--tolerate-errors |
Keep running on error. Applicable command: run |
--wait |
Run in wait mode, i.e., include think/keying sleeps. Applicable commands: init or runDefault: true |
--warehouses |
The number of warehouses for loading initial data, at approximately 200 MB per warehouse. Applicable commands: init or runDefault: 1 |
--workers |
The number of concurrent workers. Applicable commands: init or runDefault: --warehouses * 10 |
--zones |
The number of replication zones for partitioning. This number should match the number of --partitions and the zones used to start the cluster.Applicable command: init |
Logging
By default, the cockroach workload command logs errors to stderr.
If you need to troubleshoot this command's behavior, you can change its logging behavior.
Examples
These examples assume that you have already started an insecure cluster locally:
$ cockroach start \
--insecure \
--listen-addr=localhost
Run the bank workload
Load the initial schema:
$ cockroach workload init bank \ 'postgresql://root@localhost:26257?sslmode=disable'Run the workload for 1 minute:
$ cockroach workload run bank \ --duration=1m \ 'postgresql://root@localhost:26257?sslmode=disable'You'll see per-operation statistics print to standard output every second:
_elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms) 1s 0 1608.6 1702.2 4.5 7.3 12.6 65.0 transfer 2s 0 1725.3 1713.8 4.5 7.9 13.1 19.9 transfer 3s 0 1721.1 1716.2 4.5 7.3 11.5 21.0 transfer 4s 0 1328.7 1619.2 5.5 10.5 17.8 39.8 transfer 5s 0 1389.3 1573.3 5.2 11.5 16.3 23.1 transfer 6s 0 1640.0 1584.4 5.0 7.9 12.1 16.3 transfer 7s 0 1594.0 1585.8 5.0 7.9 10.5 15.7 transfer 8s 0 1652.8 1594.2 4.7 7.9 11.5 29.4 transfer 9s 0 1451.9 1578.4 5.2 10.0 15.2 26.2 transfer 10s 0 1653.3 1585.9 5.0 7.6 10.0 18.9 transfer ...After the specified duration (1 minute in this case), the workload will stop and you'll see totals printed to standard output:
_elapsed___errors_____ops(total)___ops/sec(cum)__avg(ms)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)__result 60.0s 0 84457 1407.6 5.7 5.5 10.0 15.2 167.8
Run the kv workload
Load the initial schema:
$ cockroach workload init kv \ 'postgresql://root@localhost:26257?sslmode=disable'Run the workload for 1 minute:
$ cockroach workload run kv \ --duration=1m \ 'postgresql://root@localhost:26257?sslmode=disable'You'll see per-operation statistics print to standard output every second:
_elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms) 1s 0 5095.8 5123.7 1.5 2.5 3.3 7.3 write 2s 0 4795.4 4959.6 1.6 2.8 3.5 8.9 write 3s 0 3456.5 4458.5 2.0 4.5 7.3 24.1 write 4s 0 2787.9 4040.8 2.4 6.3 12.6 30.4 write 5s 0 3558.7 3944.4 2.0 4.2 6.8 11.5 write 6s 0 3733.8 3909.3 1.9 4.2 6.0 12.6 write 7s 0 3565.6 3860.1 2.0 4.7 7.9 25.2 write 8s 0 3469.3 3811.4 2.0 5.0 6.8 22.0 write 9s 0 3937.6 3825.4 1.8 3.7 7.3 29.4 write 10s 0 3822.9 3825.1 1.8 4.7 8.9 37.7 write ...After the specified duration (1 minute in this case), the workload will stop and you'll see totals printed to standard output:
_elapsed___errors_____ops(total)___ops/sec(cum)__avg(ms)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)__result 60.0s 0 276067 4601.0 1.7 1.6 3.1 5.2 96.5
Load the intro dataset
Load the dataset:
$ cockroach workload init intro \ 'postgresql://root@localhost:26257?sslmode=disable'Launch the built-in SQL client to view it:
$ cockroach sql --insecure> SHOW TABLES FROM intro;table_name +------------+ mytable (1 row)$ SELECT * FROM intro.mytable WHERE (l % 2) = 0;l | v +----+------------------------------------------------------+ 0 | !__aaawwmqmqmwwwaas,,_ .__aaawwwmqmqmwwaaa,, 2 | !"VT?!"""^~~^"""??T$Wmqaa,_auqmWBT?!"""^~~^^""??YV^ 4 | ! "?##mW##?"- 6 | ! C O N G R A T S _am#Z??A#ma, Y 8 | ! _ummY" "9#ma, A 10 | ! vm#Z( )Xmms Y 12 | ! .j####mmm#####mm#m##6. 14 | ! W O W ! jmm###mm######m#mmm##6 16 | ! ]#me*Xm#m#mm##m#m##SX##c 18 | ! dm#||+*$##m#mm#m#Svvn##m 20 | ! :mmE=|+||S##m##m#1nvnnX##; A 22 | ! :m#h+|+++=Xmm#m#1nvnnvdmm; M 24 | ! Y $#m>+|+|||##m#1nvnnnnmm# A 26 | ! O ]##z+|+|+|3#mEnnnnvnd##f Z 28 | ! U D 4##c|+|+|]m#kvnvnno##P E 30 | ! I 4#ma+|++]mmhvnnvq##P` ! 32 | ! D I ?$#q%+|dmmmvnnm##! 34 | ! T -4##wu#mm#pw##7' 36 | ! -?$##m####Y' 38 | ! !! "Y##Y"- 40 | ! (21 rows)
Load the startrek dataset
Load the dataset:
$ cockroach workload init startrek \ 'postgresql://root@localhost:26257?sslmode=disable'Launch the built-in SQL client to view it:
$ cockroach sql --insecure> SHOW TABLES FROM startrek;table_name +------------+ episodes quotes (2 rows)> SELECT * FROM startrek.episodes WHERE stardate > 5500;id | season | num | title | stardate +----+--------+-----+-----------------------------------+----------+ 60 | 3 | 5 | Is There in Truth No Beauty? | 5630.7 62 | 3 | 7 | Day of the Dove | 5630.3 64 | 3 | 9 | The Tholian Web | 5693.2 65 | 3 | 10 | Plato's Stepchildren | 5784.2 66 | 3 | 11 | Wink of an Eye | 5710.5 69 | 3 | 14 | Whom Gods Destroy | 5718.3 70 | 3 | 15 | Let That Be Your Last Battlefield | 5730.2 73 | 3 | 18 | The Lights of Zetar | 5725.3 74 | 3 | 19 | Requiem for Methuselah | 5843.7 75 | 3 | 20 | The Way to Eden | 5832.3 76 | 3 | 21 | The Cloud Minders | 5818.4 77 | 3 | 22 | The Savage Curtain | 5906.4 78 | 3 | 23 | All Our Yesterdays | 5943.7 79 | 3 | 24 | Turnabout Intruder | 5928.5 (14 rows)
Run the tpcc workload
Load the initial schema and data:
$ cockroach workload init tpcc \ 'postgresql://root@localhost:26257?sslmode=disable'Run the workload for 10 minutes:
$ cockroach workload run tpcc \ --duration=10m \ 'postgresql://root@localhost:26257?sslmode=disable'You'll see per-operation statistics print to standard output every second:
_elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms) 1s 0 1443.4 1494.8 4.7 9.4 27.3 67.1 transfer 2s 0 1686.5 1590.9 4.7 8.1 15.2 28.3 transfer 3s 0 1735.7 1639.0 4.7 7.3 11.5 28.3 transfer 4s 0 1542.6 1614.9 5.0 8.9 12.1 21.0 transfer 5s 0 1695.9 1631.1 4.7 7.3 11.5 22.0 transfer 6s 0 1569.2 1620.8 5.0 8.4 11.5 15.7 transfer 7s 0 1614.6 1619.9 4.7 8.1 12.1 16.8 transfer 8s 0 1344.4 1585.6 5.8 10.0 15.2 31.5 transfer 9s 0 1351.9 1559.5 5.8 10.0 16.8 54.5 transfer 10s 0 1514.8 1555.0 5.2 8.1 12.1 16.8 transfer ...After the specified duration (10 minutes in this case), the workload will stop and you'll see totals printed to standard output:
_elapsed___errors_____ops(total)___ops/sec(cum)__avg(ms)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)__result 600.0s 0 823902 1373.2 5.8 5.5 10.0 15.2 209.7
