CLI Reference#

Running edg with an expression (no subcommand) evaluates it and prints the result. Bare words are treated as gofakeit patterns, so edg email is equivalent to edg "gen('email')". For expressions with parentheses or special characters, quote the argument.

A typical workflow runs the commands in order: up -> seed -> run -> down. The all command runs this entire sequence in a single invocation.

Flags#

Cassandra LWT / CAS workloads require --no-atomic-tx. Cassandra does not support lightweight transactions (IF conditions) inside batches, so transaction blocks must run each statement independently. For multi-DC consistency testing, set --cassandra-serial-consistency serial to use global Paxos consensus. A typical LWT consistency test invocation looks like:

edg run \
  --driver cassandra \
  --url "cassandra://user:pass@host1,host2,host3:9042/keyspace" \
  --cassandra-default-consistency local_quorum \
  --cassandra-serial-consistency serial \
  --no-atomic-tx \
  -w 10 -d 5m

MongoDB tuning is done via URI parameters in --url rather than dedicated flags. The MongoDB driver parses all options from the connection string, so append query parameters to control consistency, read routing, and connection behaviour. Common parameters:

Parameter	Values	Effect
w	0, 1, 2, …, majority, or a custom tag set name	Write concern. See write concern values below.
readConcernLevel	local, available, majority, linearizable, snapshot	Read isolation level. See read concern values below.
readPreference	primary, primaryPreferred, secondary, secondaryPreferred, nearest	Which replica serves reads. nearest gives lowest latency; secondary offloads the primary.
retryWrites	true, false	Retry failed writes once (default: true).
directConnection	true, false	Connect to a single node without topology discovery.
loadBalanced	true, false	Required when connecting through an L4 load balancer (e.g. Atlas Serverless).
connectTimeoutMS	milliseconds	Connection timeout (edg default: 10000).
serverSelectionTimeoutMS	milliseconds	How long the driver waits for a suitable server (edg default: 10000).

Example with majority write concern and linearizable reads:

edg run \
  --driver mongodb \
  --url "mongodb://localhost:27017/mydb?w=majority&readConcernLevel=linearizable" \
  --config workload.edg \
  -w 10 -d 5m

MongoDB write concern values#

w value	Meaning
0	Fire-and-forget. No acknowledgement from the server.
1	Acknowledged by primary only (default).
2, 3, …	Acknowledged by that many replica set members.
majority	Acknowledged by a majority of replica set members. Won’t be rolled back.
custom tag	Acknowledged by members matching a custom getLastErrorModes tag set.

MongoDB read concern values#

readConcernLevel value	Meaning
local	Most recent data from the node (default for primary reads). May be rolled back.
available	Like local but for sharded clusters. It doesn’t wait for orphaned docs to be cleaned. Lowest latency.
majority	Only data acknowledged by a majority. Won’t be rolled back.
linearizable	Reflects all successful majority writes before the read. Single-document only, primary only. Highest consistency.
snapshot	Point-in-time snapshot across a transaction. Requires w=majority. Transactions only.

For consistency testing, w=majority + readConcernLevel=majority is the common combination. snapshot is stronger but only works inside transactions. Use --retries 3 to handle transient WriteConflict errors under contention.

Every flag with an env var listed above can be set via the environment instead of the command line. Flags take precedence over environment variables, which take precedence over defaults.

export EDG_URL="postgres://root@localhost:26257?sslmode=disable"
export EDG_DRIVER="pgx"
export EDG_CONFIG="workload.edg"

# No need to pass --url, --driver, or --config:
edg run -w 10 -d 5m

# Flags override env vars when both are set:
edg run -w 10 -d 5m --driver mysql --url "user:pass@tcp(localhost:3306)/db"

Remote Config#

The --config flag accepts HTTP and HTTPS URLs. edg fetches the YAML and runs it the same as a local file.

# Serve a config directory
python3 -m http.server 8000 -d examples/tpcc

# Run edg against it
edg all \
--driver pgx \
--config "http://localhost:8000/workload.edg" \
--url "postgres://root@localhost:26257?sslmode=disable" \
-w 1 \
-d 10s

!include directives are not resolved for remote configs, since there is no local filesystem to resolve relative paths against.

Example#

Database#

Run each lifecycle command individually against a database, or use all to run the entire sequence in one invocation.

edg up \
--driver pgx \
--config examples/tpcc/crdb.edg \
--url "postgres://root@localhost:26257?sslmode=disable"

edg seed \
--driver pgx \
--config examples/tpcc/crdb.edg \
--url "postgres://root@localhost:26257?sslmode=disable"

edg run \
--driver pgx \
--config examples/tpcc/crdb.edg \
--url "postgres://root@localhost:26257?sslmode=disable" \
-w 100 \
-d 1m

edg deseed \
--driver pgx \
--config examples/tpcc/crdb.edg \
--url "postgres://root@localhost:26257?sslmode=disable"

edg down \
--driver pgx \
--config examples/tpcc/crdb.edg \
--url "postgres://root@localhost:26257?sslmode=disable"

Or use all to run the entire workflow in one command:

edg all \
--driver pgx \
--config examples/tpcc/crdb.edg \
--url "postgres://root@localhost:26257?sslmode=disable" \
-w 100 \
-d 5m

Aurora DSQL#

The dsql driver uses AWS IAM authentication instead of a username and password. Pass the cluster endpoint as the --url value:

edg all \
--driver dsql \
--config workload.edg \
--url "clusterid.dsql.us-east-1.on.aws" \
-w 10 \
-d 5m

AWS credentials are resolved from the standard chain (environment variables, ~/.aws/credentials, IAM role, etc.). The region is parsed from the cluster endpoint automatically. Auth tokens are refreshed on every new connection, so long-running workloads work without interruption.

DSQL uses PostgreSQL-compatible SQL, so use $1, $2 placeholders in your queries.

Licensing#

The pgx, mysql, mongodb, and cassandra drivers are free to use. Pro drivers (oracle, mssql, dsql, spanner) require a license key passed via --license or EDG_LICENSE. The license is validated before connecting to the database. See the Licensing page for full details.

Validating Config#

The validate config command parses a config file and checks it for errors without connecting to a database. It catches YAML syntax errors, invalid expressions, unknown function calls, duplicate query names, shadowed built-ins, and invalid query types. Errors include YAML line numbers when available.

edg validate config --config examples/tpcc/workload.edg

config is valid

Add --explain for enhanced error messages with explanations and correct syntax examples:

edg validate config --config workload.edg --explain

line 42: duplicate query name "seed_users"

  Query names must be unique across all sections. They serve as dataset keys
  for ref_* functions and as metric labels. Rename one of the duplicates.

This is useful for catching mistakes before deploying a workload or as a CI check.

Validating a License#

The validate license command checks whether a license key is valid for a given driver and prints the license details.

edg validate license --driver oracle --license "your-license-key"

License info:
  ID:         acme-corp
  Email:      admin@acme.com
  Drivers:    [oracle mssql]
  Issued at:  2025-01-15
  Expires at: 2026-01-15
License is valid for driver "oracle".

If the driver doesn’t require a license, the output tells you:

edg validate license --driver pgx --license "your-license-key"

License info:
  ID:         acme-corp
  Email:      admin@acme.com
  Drivers:    [oracle mssql]
  Issued at:  2025-01-15
  Expires at: 2026-01-15
Driver "pgx" does not require a license.

If the license is expired or doesn’t cover the requested driver, you’ll see an error:

edg validate license --driver dsql --license "your-license-key"

License info:
  ID:         acme-corp
  Email:      admin@acme.com
  Drivers:    [oracle mssql]
  Issued at:  2025-01-15
  Expires at: 2026-01-15
Error: license does not include driver "dsql" (licensed: [oracle mssql])

The EDG_LICENSE environment variable is also accepted:

export EDG_LICENSE="your-license-key"
edg validate license --driver oracle

Retries#

The --retries flag controls how many times a failed transaction is retried before the error is recorded. The default is 0 (no retries). Retries only apply to transactions (queries wrapped in a transaction: block), not standalone queries.

When a transaction fails, edg waits with exponential backoff before retrying:

If all retry attempts fail, the last error is recorded in the stats and the worker continues to the next iteration. Context cancellation (e.g. Ctrl+C or duration expiry) stops retries immediately.

edg run \
  --driver pgx \
  --config workload.edg \
  --url ${DATABASE_URL} \
  --retries 3 \
  -w 10 \
  -d 5m

Error Output#

By default, individual query errors during the run phase are counted but not printed. The --errors flag prints each error to stderr as it occurs, which is useful for debugging:

edg run \
  --driver pgx \
  --config workload.edg \
  --url ${DATABASE_URL} \
  --errors \
  -w 10 \
  -d 5m

2025/04/23 14:32:07 ERROR run error worker=3 error="running run query debit_source: pq: insufficient funds"
2025/04/23 14:32:07 ERROR run error worker=7 error="running run query debit_source: pq: insufficient funds"

Without --errors, the same failures still appear in the summary table’s ERRORS column and count toward error_rate in expectations.

Connection Pool#

The --pool-size flag sets the maximum number of open database connections (SetMaxOpenConns and SetMaxIdleConns). The default 0 uses the driver’s default, which is typically unlimited.

Setting pool size is useful for:

• Simulating constrained environments where the application has a fixed connection budget.
• Preventing connection exhaustion when running with many workers against a database with connection limits.
• Isolating connection overhead from query performance in benchmarks.

edg run \
  --driver pgx \
  --config workload.edg \
  --url ${DATABASE_URL} \
  --pool-size 20 \
  -w 50 \
  -d 5m

In this example, 50 workers share 20 connections. Workers that can’t acquire a connection will block until one becomes available.

Warmup#

The --warmup-duration flag runs workers for a specified period before collecting metrics. During warmup, query results are discarded. They don’t appear in progress output, the summary, Prometheus metrics, or expectations.

This produces cleaner benchmark results by allowing the database to warm its caches, JIT-compile query plans, and reach a steady state before measurement begins.

edg run \
  --driver pgx \
  --config workload.edg \
  --url ${DATABASE_URL} \
  --warmup-duration 30s \
  -w 10 \
  -d 5m

In this example, workers run for 30 seconds of warmup (discarded), then 5 minutes of measured execution. The total wall-clock time is 5m30s.

When using stages, warmup applies before the first stage begins collecting metrics.

Request Timeout#

The --request-timeout flag sets a default timeout for each individual query execution. When set, every query gets a context deadline of the specified duration. A query that exceeds the timeout is cancelled and counted as an error.

Per-query timeouts can be set with request_timeout in the config, which takes precedence over the global flag:

run {
  fast_lookup(request_timeout: 500ms) `SELECT * FROM users WHERE id = $1` (ref_rand('fetch_users').id)
  slow_report(request_timeout: 30s) `SELECT count(*) FROM orders GROUP BY region`
}

run:
  - name: fast_lookup
    request_timeout: 500ms
    args: [ref_rand('fetch_users').id]
    query: SELECT * FROM users WHERE id = $1

  - name: slow_report
    request_timeout: 30s
    query: SELECT count(*) FROM orders GROUP BY region

When neither a per-query request_timeout nor the global --request-timeout flag is set, queries run without a timeout (bounded only by the worker’s context).

Run Behaviour#

Workers and Initialisation#

Each worker gets its own isolated environment. The init section runs once, and its results are cloned to each worker so that functions like ref_rand and ref_diff don’t interfere across workers. Per-worker state includes sequence counters (seq), permanent row picks (ref_perm), and NURand constants.

Stages#

When a config file includes a stages section, each stage defines its own worker count and duration, and stages run sequentially. Explicitly passing -w or -d overrides the stages section and falls back to single-stage mode. See Configuration > Stages for details.

edg run \
--driver pgx \
--config examples/stages/workload.edg \
--url "postgres://root@localhost:26257?sslmode=disable"

Error Handling#

Query errors during run are non-fatal. The worker logs the error and increments an error counter but continues to the next iteration. This lets you observe error rates without aborting the benchmark. Errors in other sections (up, seed, deseed, down, init) are fatal and stop execution immediately.

Interrupting with Ctrl+C#

Pressing Ctrl+C during run or all cancels the workload gracefully. Workers finish their current iteration and stop. When using all, the cleanup phase (down) still runs after interruption, using a fresh context.

Output#

During the run, progress is printed at the --print-interval (default: every second):

59s / 1m0s
QUERY          COUNT  ERRORS  AVG      p50      p95      p99      QPS
check_balance  3674   0       2.631ms  2.367ms  4.154ms  6.252ms  62.3
credit_target  3769   0       1.68ms   1.495ms  2.624ms  3.911ms  63.9
debit_source   3769   0       2.376ms  2.13ms   3.722ms  5.288ms  63.9
read_source    3770   0       2.047ms  1.803ms  3.254ms  5.052ms  63.9
read_target    3769   0       2.839ms  2.579ms  4.486ms  6.446ms  63.9

TRANSACTION    COMMITS  ROLLBACKS  ERRORS  AVG       p50       p95       p99       TPS
make_transfer  3769     0          0       13.053ms  12.424ms  18.498ms  26.074ms  63.9

After all workers complete, a final summary is printed:

summary
Duration:  1m0.004s
Workers:   1

QUERY          COUNT  ERRORS  AVG      p50      p95      p99      QPS
check_balance  3749   0       2.628ms  2.362ms  4.14ms   6.249ms  62.5
credit_target  3828   0       1.681ms  1.497ms  2.624ms  3.911ms  63.8
debit_source   3828   1       2.381ms  2.13ms   3.724ms  5.338ms  63.8
read_source    3829   0       2.046ms  1.802ms  3.25ms   5.052ms  63.8
read_target    3829   0       2.843ms  2.583ms  4.485ms  6.446ms  63.8

TRANSACTION    COMMITS  ROLLBACKS  ERRORS  AVG       p50       p95       p99       TPS
make_transfer  3828     0          1       13.063ms  12.438ms  18.498ms  26.652ms  63.8

Transactions:  19063
Errors:        1
tpm:           19061.6

Expectations#

When the config file includes an expectations section, results are printed after the summary and the exit code reflects whether all expectations passed:

expectations
  PASS  error_rate < 1
  PASS  check_balance.p99 < 100
  FAIL  tpm > 5000

1 expectation(s) failed

If any expectation fails, edg exits with status code 1. When using all, teardown (down) still runs before the non-zero exit.

See Configuration > Expectations for the full list of available metrics and expression syntax.

Formatting#

The fmt command applies canonical formatting to .edg config files. It preserves comments, normalizes indentation to 2 spaces, and leaves SQL inside backticks untouched.

# Print formatted output to stdout.
edg fmt workload.edg

# Format in-place.
edg fmt -w workload.edg

# Format multiple files.
edg fmt -w *.edg

Running fmt twice produces identical output (idempotent). The formatted file is semantically equivalent to the original, edg validate config will produce the same result before and after formatting.

Formatting rules#

Performance Testing#

The perf command contains tools for finding the performance limits of a database.

Breakpoint PRO#

The perf breakpoint command finds the point where your database starts to degrade under load. It starts with 1 worker and adds another every --ramp-interval, monitoring latency, throughput, and errors and printing warnings whenever a percentage threshold is encountered (e.g. 50 meaning 50% more errors, 50% greater p99 latency or 50% fewer QPS). When an absolute --stop-p99, --stop-qps, or --stop-errors limit is hit, it stops and prints the summary.

edg perf breakpoint \
  --driver pgx \
  --config workload.edg \
  --url ${DATABASE_URL} \
  --ramp-interval 30s \
  --threshold 50 \
  --stop-p99 100ms

See Breakpoint Testing for flags, degradation warnings, stop conditions, and examples.