pgbench: Usage, Options & Common CI Errors
pgbench load-tests a Postgres server with a configurable TPC-B-like workload.
pgbench measures transactions per second for performance gates in CI. The first-run trap is forgetting the -i initialization step, which creates the tables the benchmark needs.
What it does
pgbench runs the same SQL transaction over and over across many client connections and reports throughput (TPS) and latency. It first needs an -i pass to build its standard tables, then runs a timed or fixed-transaction benchmark.
Common usage
PGPASSWORD=secret pgbench -h localhost -U postgres -i -s 10 app # init
pgbench -h localhost -U postgres -c 10 -j 2 -T 60 app # 60s, 10 clients
pgbench -h db -U postgres -c 4 -t 1000 app # 1000 txns per client
pgbench -h localhost -U postgres -f custom.sql -T 30 appOptions
| Flag | What it does |
|---|---|
| -i / --initialize | Create and populate the benchmark tables |
| -s <N> | Scale factor (rows = 100000 * N) |
| -c <N> | Number of concurrent clients |
| -j <N> | Number of worker threads |
| -T <secs> | Run for this many seconds |
| -t <N> | Run N transactions per client |
| -f <file> | Run a custom script instead of the default |
Common errors in CI
ERROR: relation "pgbench_accounts" does not exist - you ran the benchmark without first running pgbench -i to create the tables. "number of threads (-j) must not be higher than number of clients (-c)" - keep -j <= -c. On low-core runners a high -c/-j can saturate CPU and skew results, so pin the scale factor and concurrency and treat results as relative, not absolute.