COCKROACH-WORKLOAD-RUN-KV(1)

NAME

cockroach-workload-run-kv - KV reads and writes to keys spread randomly across the cluster.

SYNOPSIS

cockroach workload run kv [pgurl...] [flags]

DESCRIPTION

KV reads and writes to keys spread randomly across the cluster.
    By default, keys are picked uniformly at random across the cluster.
    --concurrency workers alternate between doing selects and upserts (according
    to a --read-percent ratio). Each select/upsert reads/writes a batch of --batch
    rows. The write keys are randomly generated in a deterministic fashion
    (alternatively it could changed to use --sequential or --zipfian distribution).
    Reads select a random batch of ids out of the ones previously written.
    --write-seq can be used to incorporate data produced by a previous run into
    the current run.

OPTIONS

--batch=1
    Number of blocks to read/insert in a single SQL statement.

--changefeed[=false]
    Optionally run a changefeed over the tables

--changefeed-cursor=""
    The cursor to start the changefeed from. If empty, the changefeed will start from the current cluster logical timestamp.

--changefeed-max-rate=0
    Maximum frequency of changefeed ingestion. If 0, no limit.

--changefeed-resolved-target=5s
    The target frequency of resolved messages. O to disable resolved reporting and accept server defaults.

--changefeed-start-delay=0s
    How long to wait before starting the changefeed

--concurrency=40
    Number of concurrent workers

--conn-healthcheck-period=30s
    Interval that health checks are run on connections

--conn-vars=[]
    Session variables to configure on database connections

--count-errors[=false]
    If true, unsuccessful operations count towards --max-ops limit.

--cycle-length=9223372036854775807
    Number of keys repeatedly accessed by each writer through upserts.

--data-loader="AUTO"
    How to load initial table data. All workloads support INSERT; some support IMPORT, which AUTO prefers if available.

--db=""
    Override for the SQL database to use. If empty, defaults to the generator name

--del-percent=0
    Percent (0-100) of operations that delete existing keys.

--disable-temp-hist-file[=false]
    If true, disables the use of a temporary file for incremental histogram data. Instead, data is written directly to the final file. Note: If the workload stops abruptly, the final file may become corrupted.

--display-every=1s
    How much time between every one-line activity reports.

--display-format="simple"
    Output display format (simple, incremental-json)

--dns-refresh=30s
    Interval used to refresh cached DNS entries ( disables)

--drop[=false]
    Drop the existing database, if it exists (implies --init)

--duration=0s
    The duration to run (in addition to --ramp). If 0, run forever.

--enum[=false]
    Inject an enum column and use it.

--follower-read-percent=0
    Percent (0-100) of read operations that are follower reads.

-h, --help[=false]
    help for kv

--histogram-export-format="json"
    Export format of the histogram data into the histograms file. Options: [ json, openmetrics ]

--histograms=""
    File to write per-op incremental and cumulative histogram data.

--histograms-max-latency=1m40s
    Expected maximum latency of running a query

--init[=false]
    Automatically run init. DEPRECATED: Use workload init instead.

--init-conns=16
    The number of connections to use during INSERT init

--insert-count=0
    Number of rows to insert before beginning the workload. Keys are inserted uniformly over the key range.

--isolation-level=""
    Isolation level to run workload transactions under [serializable, snapshot, read_committed]. If unset, the workload will run with the default isolation level of the database.

--key-size=0
    Use string key of appropriate size instead of int

--long-running-txn[=false]
    Use a long-running transaction for running lock contention scenarios. If run with --sfu-writes or --sel1-writes, it will use those writes in the long-running transaction; otherwise, it will use regular writes. Each long-running write transaction counts for asingle write, as measured by --read-percent.

--long-running-txn-num-writes=10
    Number of writes in the long-running transaction when using --long-running-txn.

--max-block-bytes=1
    Maximum amount of raw data written with each insertion

--max-conn-idle-time=2m30s
    Max time an idle connection will be kept around

--max-conn-lifetime=5m0s
    Max connection lifetime

--max-conn-lifetime-jitter=2m30s
    Jitter max connection lifetime by this amount

--max-ops=0
    Maximum number of operations to run

--max-rate=0
    Maximum frequency of operations (reads/writes). If 0, no limit.

--method="cache_statement"
    SQL issue method (cache_statement, cache_describe, describe_exec, exec, simple_protocol)

--min-block-bytes=1
    Minimum amount of raw data written with each insertion.

--min-conns=0
    Minimum number of connections to attempt to keep in the pool

--num-shards=0
    Number of shards to create on the primary key.

--openmetrics-labels=""
    Comma separated list of key value pairs used as labels, used by openmetrics exporter. Eg 'cloud=aws, workload=tpcc'

--operation-receiver=""
    Optional ip address:port to send latency operation metrics.

--password=""
    Optionally specify a password for the user

--prepare-read-only[=false]
    Prepare and perform only read statements.

--prometheus-port=2112
    Port to expose prometheus metrics if the workload has a prometheus gatherer set.

--ramp=0s
    The duration over which to ramp up load.

--read-percent=0
    Percent (0-100) of operations that are reads of existing keys.

--scatter[=false]
    Scatter ranges before starting normal operations.

--secondary-index[=false]
    Add a secondary index to the schema.

--secure[=false]
    Run in secure mode (sslmode=require). Running in secure mode expects the relevant certs to have been created for the user in the certs/ directory.For example when using root, certs/client.root.crt certs/client.root.key should exist.

--seed=9030416212106890320
    Random seed. Default changes in each run

--sel1-writes[=false]
    Use SELECT 1 as the first statement of transactional writes with a sleep after SELECT 1.

--sequential[=false]
    Pick keys sequentially instead of randomly.

--sfu-wait-delay=10ms
    Delay after SFU when using --sfu-writes (or after SELECT 1 when using --sel1-writes).

--sfu-writes[=false]
    Use SFU and transactional writes with a sleep after SFU.

--span-limit=0
    LIMIT count for each spanning query, or 0 for no limit

--span-percent=0
    Percent (0-100) of operations that are spanning queries of all ranges.

--splits=0
    Number of splits to perform before starting normal operations.

--target-compression-ratio=1
    Target compression ratio for data blocks. Must be >= 1.0.

--timeout=0s
    Client-side statement timeout.

--tolerate-errors[=false]
    Keep running on error

--txn-qos="regular"
    Set default_transaction_quality_of_service session variable, acceptedvalues are 'background', 'regular' and 'critical'.

--user="root"
    Specify a user to run the workload as

--warmup-conns=0
    Number of connections to warmup in each connection pool

--write-seq=""
    Initial write sequence value. Can be used to use the data produced by a previous run. It has to be of the form (R|S), where S implies that it was taken from a previous --sequential run and R implies a previous random run.

--zipfian[=false]
    Pick keys in a zipfian distribution instead of randomly.

OPTIONS INHERITED FROM PARENT COMMANDS

--enterprise-require-fips-ready[=false]
    abort if FIPS readiness checks fail

--log=

Logging configuration, expressed using YAML syntax. For example, you can
 change the default logging directory with: --log='file-defaults: {dir: ...}'.
 See the documentation for more options and details. To preview how the log
 configuration is applied, or preview the default configuration, you can use
 the 'cockroach debug check-log-config' sub-command.

--log-config-file=

File name to read the logging configuration from. This has the same effect as
 passing the content of the file via the --log flag.

--log-config-vars=[]

Environment variables that will be expanded if present in the body of the
 logging configuration.

--log-dir=

--log-dir=XXX is an alias for --log='file-defaults: {dir: XXX}'.

--logtostderr[=UNKNOWN]

--logtostderr=XXX is an alias for --log='sinks: {stderr: {filter: XXX}}'. If
 no value is specified, the default value for the command is inferred: INFO for
 server commands, WARNING for client commands.

--redactable-logs=false

--redactable-logs=XXX is an alias for --log='file-defaults: {redactable:
 XXX}}'.

--vmodule=
    comma-separated list of pattern=N settings for file-filtered logging (significantly hurts performance)

SEE ALSO

cockroach-workload-run(1)

HISTORY

13-May-2026 Auto generated by spf13/cobra