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#

Flags are grouped by scope. Global flags work anywhere and may be given before or after the subcommand; every other flag belongs to the commands listed with its group and must come after the subcommand:

edg run --url ... --config ...   # correct
edg --url ... run --config ...   # unknown flag: --url

Run edg <command> --help to see exactly which flags a command accepts.

Global Flags#

Accepted by every command.

Connection Flags#

Accepted by up, seed, deseed, down, run, all, workload, perf, and jobs. compare, sync, and cluster take everything below except --url, which their own --a-url/--source-url/--target-url flags replace. init and capture take --url only.

Workload Flags#

Accepted by the commands that drive workers: run, all, workload, perf, jobs, cluster, and compare.

Per-Command Flags#

Registered on the individual commands that support them.

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 config 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, cassandra, sqlite, and redis 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 syntax errors, invalid expressions, unknown function calls, duplicate query names, shadowed built-ins, and invalid query types. Errors include 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#

Three flags tune the connection pool: --pool-size, --max-conn-lifetime, and --max-conn-lifetime-jitter.

Pool size#

The --pool-size flag sets the maximum number of open database connections. Left at the default 0, the pool is sized to the command’s --workers value so each worker gets its own connection.

Setting pool size explicitly 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.

The value is used verbatim. With a staged config, if the busiest stage asks for more workers than the pool has connections, edg logs a warning and the workers contend.

Connection lifetime#

The --max-conn-lifetime flag caps how long a connection lives before it’s closed and replaced, defaulting to 30m. Recycling connections exercises reconnect paths and lets a client rebalance across cluster nodes after a topology change. Set it to 0 to keep connections for the whole run.

--max-conn-lifetime-jitter (default 5m) adds a random duration of up to that length to each connection’s lifetime, so a pool opened at the same moment doesn’t recycle in lockstep.

Driver support#

Unsupported settings are ignored rather than rejected, so the same flags work across drivers.

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('fetch_users').id)
  slow_report(request_timeout: 30s) `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).

Safety Caps#

The --max-rows, --max-duration, and --max-queries flags set hard ceilings on work performed, preventing runaway workloads from consuming unbounded resources.

Numbers can be provided in the following formats:

--max-rows#

Limits the total number of rows inserted during seeding. Once the cap is reached, remaining seed queries are skipped and seeding completes normally. The last query that starts may slightly overshoot the limit.

Available on: seed, all

edg seed \
  --driver pgx \
  --config workload.edg \
  --url ${DATABASE_URL} \
  --max-rows 500K

--max-duration#

Sets a wall-clock timeout on the command. When time expires, the context is cancelled and work stops gracefully.

• On seed: caps the seed phase
• On run: caps the entire run, including all stages
• On all: caps the full lifecycle (up, seed, run, deseed, down)

This is independent of --duration, which sets the benchmark measurement period for the run phase. Use --max-duration as an outer safety net.

edg all \
  --driver pgx \
  --config workload.edg \
  --url ${DATABASE_URL} \
  -w 10 \
  -d 1h \
  --max-duration 30m

--max-queries#

Limits the total number of query executions during the run phase. Workers check the counter after each iteration and stop when the cap is reached. The count is shared across all workers.

Available on: run, all

edg run \
  --driver pgx \
  --config workload.edg \
  --url ${DATABASE_URL} \
  -w 10 \
  -d 1h \
  --max-queries 1M

--max-qps#

Limits the total number of queries per second during the run phase. The rate is shared across all workers, guaranteeing a ceiling to QPS regardless of worker count.

It’s a ceiling, not a target: when a stage declares its own lower qps, the stage rate still applies, and a stage asking for more than --max-qps is held at the cap.

Available on: run, all

edg run \
  --driver pgx \
  --config workload.edg \
  --url ${DATABASE_URL} \
  -w 10 \
  -d 1h \
  --max-qps 1K

Command availability#

Environment variables#

All three flags can be set via environment variables:

export EDG_MAX_ROWS=1M
export EDG_MAX_DURATION=30m
export EDG_MAX_QUERIES=500K

Flags take precedence over environment variables.

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  p90      p95      p99      QPS
check_balance  3674   0       3.584ms  4.154ms  6.252ms  62.3
credit_target  3769   0       2.261ms  2.624ms  3.911ms  63.9
debit_source   3769   0       3.214ms  3.722ms  5.288ms  63.9
read_source    3770   0       2.806ms  3.254ms  5.052ms  63.9
read_target    3769   0       3.871ms  4.486ms  6.446ms  63.9

TRANSACTION    COMMITS  ROLLBACKS  ERRORS  p90       p95       p99       TPS
make_transfer  3769     0          0       15.923ms  18.498ms  26.074ms  63.9

After all workers complete, a final summary is printed:

summary
Duration:  1m0.004s
Workers:   1

QUERY          COUNT  ERRORS  p90      p95      p99      QPS
check_balance  3749   0       3.571ms  4.14ms   6.249ms  62.5
credit_target  3828   0       2.261ms  2.624ms  3.911ms  63.8
debit_source   3828   1       3.216ms  3.724ms  5.338ms  63.8
read_source    3829   0       2.803ms  3.25ms   5.052ms  63.8
read_target    3829   0       3.868ms  4.485ms  6.446ms  63.8

TRANSACTION    COMMITS  ROLLBACKS  ERRORS  p90       p95       p99       TPS
make_transfer  3828     0          1       15.923ms  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, reorders top-level blocks into a canonical order, 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#

Block order#

fmt moves top-level blocks into the order below, taking each block’s comments with it. Blocks of the same kind (and seq/signal/season, which share a slot) keep the order they were written in.

include, import and csv are pinned to the top, because the parser rejects them after any declaration.

include
import
csv
let
expr
seq / signal / season
ref
object
tree
template
complete
workers
up
seed
stages
weights
init
run
stats
deseed
down
expect

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.