pgbent is a benchmarking toolkit for testing PostgreSQL databases. As a performance regression testing tool, it's uncovered package integration and/or performance issues in three successive PostgreSQL releases, 16-18.

pgbent includes load generation orchestration features with arbitrary workload scripts and metrics collection going into a PG database for analysis. Analysis options include SQL reporting plus a Streamlit based results explorer.

• Documentation
• Results explorer: sample results from the testing done for Postgres 14-18.

pgbench is the best supported load generator but you can supply any script. pgbent writes to a results database comparing metrics across multiple runs, recording second level precision system metrics and whatever arbitrary database internals queries you want to attach. A sample connection count query is bundled, you can change or extend that to collect anything you can read via SQL--which for Postgres means just about anything!

While there are plenty of other options for running PostgreSQL scripts and collecting system metrics, the way pgbent is assembled is aimed at providing repeatable standard workloads that can be used for regression testing and audited for correctness. That tookit has allowed creating a small set of novel synthetic database workloads that target the known strong and weak spots of modern storage, as well as ones that respond predictably to database tuning. Database storage is tricky stuff, and the customer metric collector avoided the typical monitoring tool time averaging that obliterates the interesting GB/s peak behavior of modern SSD.

For a few years now, the most interesting benchmark results have been the Open Street Map tests, published as blog entries, talks, or social media posts. That runs via the pgbent's artibrary workload interface script.

There's also a storage stress test workload included, Complete Block Check. That runs anywhere you want, from a psql session to orchestrated via pgbench generating its workload. It even runs on the web based Postgres Playground where it can be used to compare web browser block performance. Seriously!

Known issues

• On Solaris, where the benchwarmer script calls tail it may need to use /usr/xpg4/bin/tail instead

Planned features

The planned follow up tech refresh coming in later 2025 is deprecating use of gnuplot in favor of Python Pandas based graphs. Right now Pandas is behind the most recent slides and social media graph posts. There are still a few old gnuplot graphs left to replace.

Some older ideas that may be implemented include:

• Graphs for buffers/checkpoints throughtout
• Fix the static number of scales/clients for rates_webreport
• Fix zombie files when benchmark crashes and OS stats processes are left behind

Contact

The project is hosted at https://github.com/gregs1104/pgbent

There are old versions hosted on by the PostgreSQL project at http://git.postgresql.org/git/pgbench-tools.git or http://git.postgresql.org/gitweb that have not been updated in some time now.

If you have any hints, changes, improvements, or please contact:

• Greg Smith [email protected]

Notable forks

• Future featured upgrades and bug fixes: https://github.com/emerichunter/pgbench-tools
• Full bash to Python port adding Windows compatibility: https://github.com/rugging24/pg_pybench

Credits

Copyright (c) 2007-2025, Gregory Smith All rights reserved. See COPYRIGHT file for full license details and HISTORY for a full list of other contributions to the program.

Major contributors:

• Josh Kupershmidt [email protected]
• Emeric Tabakhoff [email protected] or [email protected]

---

References:

1. Introduction 1 & 2 and in french 1 & 2