Run a Sample Workload

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

  1. # Create the schema for a workload:
  2. $ cockroach workload init <workload> <flags> '<connection string>'
  4. # Run a workload:
  5. $ cockroach workload run <workload> <flags> '<connection string>'
  7. # View help:
  8. $ cockroach workload --help
  9. $ cockroach workload init --help
  10. $ cockroach workload init <workload> --help
  11. $ cockroach workload run --help
  12. $ cockroach workload run <workload> --help

Subcommands

CommandUsage
initLoad the schema for the workload. You run this command once for a given schema.
runRun 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 —concurrency flag 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

WorkloadDescription
bankModels 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.
introLoads 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.
kvReads 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.
startrekLoads 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.
tpccSimulates 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.
ycsbSimulates a high-scale key value workload, either read-heavy, write-heavy, or scan-based, with additional customizations.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

FlagDescription
—concurrencyThe number of concurrent workers.Applicable commands: init or runDefault: 2 number of CPUs
—dbThe SQL database to use.Applicable commands: init or runDefault: bank
—dropDrop the existing database, if it exists.Applicable commands: init or run. For the run command, this flag must be used in conjunction with —init.
—durationThe 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.
—histogramsThe file to write per-op incremental and cumulative histogram data to.Applicable command: run
—initAutomatically run the init command.Applicable command: run
—max-opsThe maximum number of operations to run.Applicable command: run
—max-rateThe maximum frequency of operations (reads/writes).Applicable command: runDefault: 0, which means unlimited.
—payload-bytesThe size of the payload field in each initial row.Applicable commands: init or runDefault: 100
—rampThe duration over which to ramp up load.Applicable command: run
—rangesThe initial number of ranges in the bank table.Applicable commands: init or runDefault: 10
—rowsThe initial number of accounts in the bank table.Applicable commands: init or runDefault: 1000
—seedThe key hash seed.Applicable commands: init or runDefault: 1
—tolerate-errorsKeep 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.

FlagDescription
—dropDrop the existing database, if it exists, before loading the dataset.

kv workload

FlagDescription
—batchThe number of blocks to insert in a single SQL statement.Applicable commands: init or runDefault: 1
—concurrencyThe number of concurrent workers.Applicable commands: init or runDefault: 8 —cycle-length
—dbThe SQL database to use.Applicable commands: init or runDefault: kv
—dropDrop the existing database, if it exists.Applicable commands: init or run
—durationThe 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.
—histogramsThe file to write per-op incremental and cumulative histogram data to.Applicable command: run
—initAutomatically run the init command.Applicable command: run
—max-block-bytesThe maximum amount of raw data written with each insertion.Applicable commands: init or runDefault: 2
—max-opsThe maximum number of operations to run.Applicable command: run
—max-rateThe maximum frequency of operations (reads/writes).Applicable command: runDefault: 0, which means unlimited.
—min-block-bytesThe minimum amount of raw data written with each insertion.Applicable commands: init or runDefault: 1
—rampThe duration over which to ramp up load.Applicable command: run
—read-percentThe percent (0-100) of operations that are reads of existing keys.Applicable commands: init or run
—seedThe key hash seed.Applicable commands: init or runDefault: 1
—sequentialPick keys sequentially instead of randomly.Applicable commands: init or run
—splitsThe number of splits to perform before starting normal operations.Applicable commands: init or run
—tolerate-errorsKeep running on error.Applicable command: run
—use-optUse cost-based optimizer.Applicable commands: init or runDefault: true
—write-seqInitial write sequence value.Applicable commands: init or run

tpcc workload

FlagDescription
—active-warehousesRun the load generator against a specific number of warehouses.Applicable commands: init or runDefaults: Value of —warehouses
—dbThe SQL database to use.Applicable commands: init or runDefault: tpcc
—dropDrop the existing database, if it exists.Applicable commands: init or run. For the run command, this flag must be used in conjunction with —init.
—durationThe 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.
—fksAdd foreign keys.Applicable commands: init or runDefault: true
—histogramsThe file to write per-op incremental and cumulative histogram data to.Applicable command: run
—initAutomatically run the init command.Applicable command: run
—interleavedUse interleaved tables.Applicable commands: init or run
—max-opsThe maximum number of operations to run.Applicable command: run
—max-rateThe maximum frequency of operations (reads/writes).Applicable command: runDefault: 0, which means unlimited.
—mixWeights 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-affinityRun the load generator against a specific partition. This flag must be used in conjunction with —partitions.Applicable commands: init or runDefault: -1
—partitionsPartition tables. This flag must be used in conjunction with —split.Applicable commands: init or run
—rampThe duration over which to ramp up load.Applicable command: run
—scatterScatter ranges.Applicable commands: init or run
—seedThe random number generator seed.Applicable commands: init or runDefault: 1
—serializableForce serializable mode. CockroachDB only supports SERIALIZABLE isolation, so this flag is not necessary.Applicable command: init
—splitSplit tables.Applicable commands: init or run
—tolerate-errorsKeep running on error.Applicable command: run
—waitRun in wait mode, i.e., include think/keying sleeps.Applicable commands: init or runDefault: true
—warehousesThe number of warehouses for loading initial data, at approximately 200 MB per warehouse.Applicable commands: init or runDefault: 1
—workersThe number of concurrent workers.Applicable commands: init or runDefault: —warehouses 10
—zonesThe 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

ycsb workload

FlagDescription
—concurrencyThe number of concurrent workers.Applicable commands: init or runDefault: 8
—dbThe SQL database to use.Applicable commands: init or runDefault: ycsb
—dropDrop the existing database, if it exists.Applicable commands: init or run. For the run command, this flag must be used in conjunction with —init.
—durationThe 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.
—familiesPlace each column in its own column family.Applicable commands: init or run
—histogramsThe file to write per-op incremental and cumulative histogram data to.Applicable command: run
—initAutomatically run the init command.Applicable command: run
—initial-rowsInitial number of rows to sequentially insert before beginning random number generation.Applicable commands: init or runDefault: 10000
—jsonUse JSONB rather than relational data.Applicable commands: init or run
—max-opsThe maximum number of operations to run.Applicable command: run
—max-rateThe maximum frequency of operations (reads/writes).Applicable command: runDefault: 0, which means unlimited.
—methodThe SQL issue method (prepare, noprepare, simple).Applicable commands: init or runDefault: prepare
—pprofportThe port for pprof endpoint.Applicable commands: init or run. For the run command, this flag must be used in conjunction with —init.Default: 33333
—rampThe duration over which to ramp up load.Applicable command: run
—request-distributionDistribution for the random number generator (zipfian, uniform).Applicable commands: init or run.Default: zipfian
—seedThe random number generator seed.Applicable commands: init or runDefault: 1
—splitsNumber of splits to perform before starting normal operations.Applicable commands: init or run
—tolerate-errorsKeep running on error.Applicable command: run
—workloadThe type of workload to run (A, B, C, D, or F). For details about these workloads, see YCSB Workloads.Applicable commands: init or runDefault: B

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:

  1. $ cockroach start \
  2. --insecure \
  3. --listen-addr=localhost

Run the bank workload

  • Load the initial schema:
  1. $ cockroach workload init bank \
  2. 'postgresql://root@localhost:26257?sslmode=disable'
  • Run the workload for 1 minute:
  1. $ cockroach workload run bank \
  2. --duration=1m \
  3. 'postgresql://root@localhost:26257?sslmode=disable'

You'll see per-operation statistics print to standard output every second:

  1. _elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)
  2.       1s        0         1608.6         1702.2      4.5      7.3     12.6     65.0 transfer
  3.       2s        0         1725.3         1713.8      4.5      7.9     13.1     19.9 transfer
  4.       3s        0         1721.1         1716.2      4.5      7.3     11.5     21.0 transfer
  5.       4s        0         1328.7         1619.2      5.5     10.5     17.8     39.8 transfer
  6.       5s        0         1389.3         1573.3      5.2     11.5     16.3     23.1 transfer
  7.       6s        0         1640.0         1584.4      5.0      7.9     12.1     16.3 transfer
  8.       7s        0         1594.0         1585.8      5.0      7.9     10.5     15.7 transfer
  9.       8s        0         1652.8         1594.2      4.7      7.9     11.5     29.4 transfer
  10.       9s        0         1451.9         1578.4      5.2     10.0     15.2     26.2 transfer
  11.      10s        0         1653.3         1585.9      5.0      7.6     10.0     18.9 transfer
  12. ...

After the specified duration (1 minute in this case), the workload will stop and you'll see totals printed to standard output:

  1. _elapsed___errors_____ops(total)___ops/sec(cum)__avg(ms)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)__result
  2.    60.0s        0          84457         1407.6      5.7      5.5     10.0     15.2    167.8

Run the kv workload

  • Load the initial schema:
  1. $ cockroach workload init kv \
  2. 'postgresql://root@localhost:26257?sslmode=disable'
  • Run the workload for 1 minute:
  1. $ cockroach workload run kv \
  2. --duration=1m \
  3. 'postgresql://root@localhost:26257?sslmode=disable'

You'll see per-operation statistics print to standard output every second:

  1. _elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)
  2.       1s        0         5095.8         5123.7      1.5      2.5      3.3      7.3 write
  3.       2s        0         4795.4         4959.6      1.6      2.8      3.5      8.9 write
  4.       3s        0         3456.5         4458.5      2.0      4.5      7.3     24.1 write
  5.       4s        0         2787.9         4040.8      2.4      6.3     12.6     30.4 write
  6.       5s        0         3558.7         3944.4      2.0      4.2      6.8     11.5 write
  7.       6s        0         3733.8         3909.3      1.9      4.2      6.0     12.6 write
  8.       7s        0         3565.6         3860.1      2.0      4.7      7.9     25.2 write
  9.       8s        0         3469.3         3811.4      2.0      5.0      6.8     22.0 write
  10.       9s        0         3937.6         3825.4      1.8      3.7      7.3     29.4 write
  11.      10s        0         3822.9         3825.1      1.8      4.7      8.9     37.7 write
  12. ...

After the specified duration (1 minute in this case), the workload will stop and you'll see totals printed to standard output:

  1. _elapsed___errors_____ops(total)___ops/sec(cum)__avg(ms)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)__result
  2.    60.0s        0         276067         4601.0      1.7      1.6      3.1      5.2     96.5

Load the intro dataset

  • Load the dataset:
  1. $ cockroach workload init intro \
  2. 'postgresql://root@localhost:26257?sslmode=disable'
  • Launch the built-in SQL client to view it:
  1. $ cockroach sql --insecure
  1. > SHOW TABLES FROM intro;
  1.   table_name
  2. +------------+
  3.   mytable
  4. (1 row)
  1. $ SELECT * FROM intro.mytable WHERE (l % 2) = 0;
  1.   l  |                          v
  2. +----+------------------------------------------------------+
  3.    0 | !__aaawwmqmqmwwwaas,,_        .__aaawwwmqmqmwwaaa,,
  4.    2 | !"VT?!"""^~~^"""??T$Wmqaa,_auqmWBT?!"""^~~^^""??YV^
  5.    4 | !                    "?##mW##?"-
  6.    6 | !  C O N G R A T S  _am#Z??A#ma,           Y
  7.    8 | !                 _ummY"    "9#ma,       A
  8.   10 | !                vm#Z(        )Xmms    Y
  9.   12 | !              .j####mmm#####mm#m##6.
  10.   14 | !   W O W !    jmm###mm######m#mmm##6
  11.   16 | !             ]#me*Xm#m#mm##m#m##SX##c
  12.   18 | !             dm#||+*$##m#mm#m#Svvn##m
  13.   20 | !            :mmE=|+||S##m##m#1nvnnX##;     A
  14.   22 | !            :m#h+|+++=Xmm#m#1nvnnvdmm;     M
  15.   24 | ! Y           $#m>+|+|||##m#1nvnnnnmm#      A
  16.   26 | !  O          ]##z+|+|+|3#mEnnnnvnd##f      Z
  17.   28 | !   U  D       4##c|+|+|]m#kvnvnno##P       E
  18.   30 | !       I       4#ma+|++]mmhvnnvq##P`       !
  19.   32 | !        D I     ?$#q%+|dmmmvnnm##!
  20.   34 | !           T     -4##wu#mm#pw##7'
  21.   36 | !                   -?$##m####Y'
  22.   38 | !             !!       "Y##Y"-
  23.   40 | !
  24. (21 rows)

Load the startrek dataset

  • Load the dataset:
  1. $ cockroach workload init startrek \
  2. 'postgresql://root@localhost:26257?sslmode=disable'
  • Launch the built-in SQL client to view it:
  1. $ cockroach sql --insecure
  1. > SHOW TABLES FROM startrek;
  1.   table_name
  2. +------------+
  3.   episodes
  4.   quotes
  5. (2 rows)
  1. > SELECT * FROM startrek.episodes WHERE stardate > 5500;
  1.   id | season | num |               title               | stardate
  2. +----+--------+-----+-----------------------------------+----------+
  3.   60 |      3 |   5 | Is There in Truth No Beauty?      |   5630.7
  4.   62 |      3 |   7 | Day of the Dove                   |   5630.3
  5.   64 |      3 |   9 | The Tholian Web                   |   5693.2
  6.   65 |      3 |  10 | Plato's Stepchildren              |   5784.2
  7.   66 |      3 |  11 | Wink of an Eye                    |   5710.5
  8.   69 |      3 |  14 | Whom Gods Destroy                 |   5718.3
  9.   70 |      3 |  15 | Let That Be Your Last Battlefield |   5730.2
  10.   73 |      3 |  18 | The Lights of Zetar               |   5725.3
  11.   74 |      3 |  19 | Requiem for Methuselah            |   5843.7
  12.   75 |      3 |  20 | The Way to Eden                   |   5832.3
  13.   76 |      3 |  21 | The Cloud Minders                 |   5818.4
  14.   77 |      3 |  22 | The Savage Curtain                |   5906.4
  15.   78 |      3 |  23 | All Our Yesterdays                |   5943.7
  16.   79 |      3 |  24 | Turnabout Intruder                |   5928.5
  17. (14 rows)

Run the tpcc workload

  • Load the initial schema and data:
  1. $ cockroach workload init tpcc \
  2. 'postgresql://root@localhost:26257?sslmode=disable'
  • Run the workload for 10 minutes:
  1. $ cockroach workload run tpcc \
  2. --duration=10m \
  3. 'postgresql://root@localhost:26257?sslmode=disable'

You'll see per-operation statistics print to standard output every second:

  1. _elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)
  2.       1s        0         1443.4         1494.8      4.7      9.4     27.3     67.1 transfer
  3.       2s        0         1686.5         1590.9      4.7      8.1     15.2     28.3 transfer
  4.       3s        0         1735.7         1639.0      4.7      7.3     11.5     28.3 transfer
  5.       4s        0         1542.6         1614.9      5.0      8.9     12.1     21.0 transfer
  6.       5s        0         1695.9         1631.1      4.7      7.3     11.5     22.0 transfer
  7.       6s        0         1569.2         1620.8      5.0      8.4     11.5     15.7 transfer
  8.       7s        0         1614.6         1619.9      4.7      8.1     12.1     16.8 transfer
  9.       8s        0         1344.4         1585.6      5.8     10.0     15.2     31.5 transfer
  10.       9s        0         1351.9         1559.5      5.8     10.0     16.8     54.5 transfer
  11.      10s        0         1514.8         1555.0      5.2      8.1     12.1     16.8 transfer
  12. ...

After the specified duration (10 minutes in this case), the workload will stop and you'll see totals printed to standard output:

  1. _elapsed___errors_____ops(total)___ops/sec(cum)__avg(ms)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)__result
  2.   600.0s        0         823902         1373.2      5.8      5.5     10.0     15.2    209.7

Run the ycsb workload

  • Load the initial schema and data:
  1. $ cockroach workload init ycsb \
  2. 'postgresql://root@localhost:26257?sslmode=disable'
  • Run the workload for 10 minutes:
  1. $ cockroach workload run ycsb \
  2. --duration=10m \
  3. 'postgresql://root@localhost:26257?sslmode=disable'

You'll see per-operation statistics print to standard output every second:

  1. _elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)
  2.       1s        0         9258.1         9666.6      0.7      1.3      2.0      8.9 read
  3.       1s        0          470.1          490.9      1.7      2.9      4.1      5.0 update
  4.       2s        0        10244.6         9955.6      0.7      1.2      2.0      6.6 read
  5.       2s        0          559.0          525.0      1.6      3.1      6.0      7.3 update
  6.       3s        0         9870.8         9927.4      0.7      1.4      2.4     10.0 read
  7.       3s        0          500.0          516.6      1.6      4.2      7.9     15.2 update
  8.       4s        0         9847.2         9907.3      0.7      1.4      2.4     23.1 read
  9.       4s        0          506.8          514.2      1.6      3.7      7.6     17.8 update
  10.       5s        0        10084.4         9942.6      0.7      1.3      2.1      7.1 read
  11.       5s        0          537.2          518.8      1.5      3.5     10.0     15.2 update
  12. ...

After the specified duration (10 minutes in this case), the workload will stop and you'll see totals printed to standard output:

  1. _elapsed___errors_____ops(total)___ops/sec(cum)__avg(ms)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)__result
  2.   600.0s        0        4728286         7880.2      1.0      0.9      2.2      5.2    268.4

See also

Was this page helpful?
YesNo