utilities/personal/tools/pgbench_quickstart.md

pgbench benchmark quickstart

This workspace now includes repeatable benchmark harnesses:

• pgbench_benchmark.ps1 (Windows PowerShell)
• pgbench_benchmark.sh (Bash)
• pgbench_custom_workload.sql (sample custom SQL transaction mix)
• pgbench_export_report.py (exports TPS/latency chart report from summary.csv)

1) Prerequisites

• PostgreSQL client tools installed (psql, pgbench)
• Network access to your PostgreSQL server
• Credentials available via environment variables (PGHOST, PGPORT, PGUSER, PGPASSWORD)

2) Run the benchmark (Windows PowerShell)

From this folder:

$env:PGPASSWORD = "your_password"
.\pgbench_benchmark.ps1 -PgHost localhost -PgPort 5432 -PgUser postgres

You can override defaults:

$env:PGPASSWORD = "your_password"
.\pgbench_benchmark.ps1 -BenchDb pgbench -Scale 100 -Duration 120 -Clients "1 8 16 32 64" -Jobs 8 -Reinit $true

Run with custom SQL workload mode enabled:

$env:PGPASSWORD = "your_password"
.\pgbench_benchmark.ps1 -RunCustom $true -CustomSqlFile .\pgbench_custom_workload.sql -CustomModeName app_like -CustomReadPct 85 -CustomHotPct 92 -CustomTxnSize 3 -CustomHotAccounts 12000

3) Optional Bash usage (WSL/Git Bash)

chmod +x pgbench_benchmark.sh
PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD=your_password ./pgbench_benchmark.sh

Run with custom SQL workload mode enabled:

PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD=your_password RUN_CUSTOM=1 CUSTOM_SQL_FILE=./pgbench_custom_workload.sql CUSTOM_MODE_NAME=app_like CUSTOM_READ_PCT=85 CUSTOM_HOT_PCT=92 CUSTOM_TXN_SIZE=3 CUSTOM_HOT_ACCOUNTS=12000 ./pgbench_benchmark.sh

4) Optional tuning inputs (Bash script)

BENCH_DB=pgbench SCALE=100 DURATION=120 CLIENTS="1 8 16 32 64" JOBS=8 REINIT=1 ./pgbench_benchmark.sh

Environment variables:

• BENCH_DB: database name for benchmark data (default: pgbench)
• SCALE: data size scale factor (default: 50)
• DURATION: measured run time per test case in seconds (default: 60)
• CLIENTS: space-separated client counts (default: "1 4 8 16 32")
• JOBS: worker threads for pgbench (default: 4)
• WARMUP_SECONDS: unmeasured warm-up before each test (default: 15)
• RUN_READ_ONLY: set to 0 to skip -S read-only tests (default: 1)
• REINIT: set to 1 to reinitialize data each run (default: 0)
• RUN_CUSTOM: set to 1 to run custom SQL workload mode (default: 0)
• CUSTOM_SQL_FILE: path to custom SQL file for pgbench -f (default: pgbench_custom_workload.sql)
• CUSTOM_MODE_NAME: mode label written to summary.csv for custom runs (default: custom_sql)
• CUSTOM_READ_PCT / -CustomReadPct: read share percentage for custom mode; writes happen in 100-read_pct (default: 80)
• CUSTOM_HOT_PCT / -CustomHotPct: chance to pick from hot account set in custom mode (default: 90)
• CUSTOM_TXN_SIZE / -CustomTxnSize: custom transaction size tier from 1 to 4 (default: 2)
• CUSTOM_HOT_ACCOUNTS / -CustomHotAccounts: number of hot accounts near start of keyspace (default: 10000)

5) Output

Each run creates:

• pgbench_results_YYYYMMDD_HHMMSS/summary.csv
• Per-test raw output files in the same results directory

Use summary.csv to compare TPS and latency across runs.

summary.csv now includes percentile latency columns:

• p95_ms
• p99_ms

6) Export chart report from summary.csv

Generate an HTML report with TPS and latency charts:

python .\pgbench_export_report.py .\pgbench_results_YYYYMMDD_HHMMSS\summary.csv

Optional output path:

python .\pgbench_export_report.py .\pgbench_results_YYYYMMDD_HHMMSS\summary.csv -o .\pgbench_results_YYYYMMDD_HHMMSS\my_report.html