pgbench

pgbench is the benchmarking utility shipped with PostgreSQL. It is the standard first tool reached for when measuring a PostgreSQL instance's transactional throughput, because it is built in, simple to run, and supports custom SQL scripts. Its default workload is based on TPC-B, a simple banking benchmark, but its real value today is running arbitrary user-defined transactions.

What It Measures

pgbench reports transactions per second (TPS), with and without connection-establishment overhead, plus average latency and, optionally, latency percentiles and per-statement timing. Its built-in workload measures a simple update-heavy banking transaction; custom scripts can measure any query mix you define.

Methodology

The default schema models a bank with accounts, tellers, and branches, populated to a chosen scale factor (each unit adds 100,000 accounts). The standard transaction updates an account balance, updates teller and branch totals, and inserts a history row — a write-heavy pattern with contention on the small branches and tellers tables. You set the number of client connections, the number of threads, and either a transaction count or a run duration. pgbench can also run in a read-only select-only mode, or execute custom -f script files with variables and meta-commands, letting you reproduce application-specific workloads. It reports aggregate TPS and latency at the end and can sample latency over time.

How to Interpret Results

Always state the scale factor, client and thread counts, and whether the run was the default mix or select-only — write contention on small tables makes the default workload very sensitive to scale factor. Increase the scale factor so the data set exceeds shared_buffers if you want to test storage rather than cache. Sweep client counts to find the saturation point. For meaningful application benchmarks, replace the default script with custom scripts that mirror your real queries, since the TPC-B banking pattern rarely matches production.

Limitations

The built-in workload is a 1980s-era simple banking transaction and is not representative of modern applications; its heavy contention on tiny tables can mislead. pgbench is single-purpose to PostgreSQL, so it cannot be used for cross-engine comparison. As a self-run tool it produces relative, configuration-dependent numbers rather than audited results. Use it for tuning and regression testing within PostgreSQL, ideally with custom scripts. Its tight integration with PostgreSQL, including per-statement latency reporting and custom script support, makes it the natural starting point for any PostgreSQL tuning or capacity exercise. For regression testing, teams pin the scale factor, client count, and script, then track TPS across PostgreSQL releases and configuration changes to catch performance drift early.