pgbench(1)
pgbench is a simple program for running benchmark tests against a PostgreSQL database.
Synopsis
pgbench [OPTION]... [DBNAME]Description
pgbench is a benchmarking tool for PostgreSQL that simulates concurrent database clients executing transactions. It comes with a standard TPC-B like test, but custom test scenarios can be defined using SQL scripts.
The tool is useful for measuring the performance of PostgreSQL under various loads, tuning configuration parameters, and comparing different hardware or PostgreSQL versions. It can generate detailed reports showing transaction rates, latency statistics, and aggregate performance metrics.
Common options
| Flag | What it does |
|---|---|
-i, --initialize | Create and populate the benchmark tables (required before first run) |
-c, --client=NUM | Number of concurrent database clients (default: 1) |
-j, --jobs=NUM | Number of worker threads (default: 1) |
-t, --transactions=NUM | Number of transactions each client runs (default: 10) |
-T, --time=SECS | Run for this many seconds instead of a fixed transaction count |
-s, --scale=SCALE | Scale factor: multiplies the number of rows (default: 1) |
-r, --report-latencies | Report per-transaction latencies, not just aggregates |
-P, --progress=SECS | Show progress report every N seconds |
-f, --file=SCRIPTFILE | Use custom SQL script file instead of built-in TPC-B test |
-d, --debug | Print debug output |
-h, --host=HOSTNAME | PostgreSQL server host or socket directory |
-U, --username=USERNAME | PostgreSQL user name |
Examples
Initialize benchmark database 'testdb' with scale factor 10 (1 million rows in pgbench_accounts table)
pgbench -i -s 10 testdbRun benchmark with 10 concurrent clients, 2 worker threads, each running 1000 transactions
pgbench -c 10 -j 2 -t 1000 testdbRun benchmark for 60 seconds with 20 concurrent clients, reporting per-transaction latencies
pgbench -c 20 -T 60 -r testdbRun with 5 clients, 4 jobs, display progress every 10 seconds, 500 transactions each
pgbench -c 5 -j 4 -P 10 -t 500 testdbRun benchmark using custom SQL script file with 15 concurrent clients
pgbench -f custom_test.sql -c 15 -t 2000 testdbReinitialize benchmark tables with scale factor 5, dropping old tables first
pgbench -i --drop-tables -s 5 testdbRun 5-minute benchmark with 8 clients on localhost, reporting latencies, using postgres user
pgbench -c 8 -T 300 -r -h localhost -U postgres testdb