# 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:

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

You can override defaults:

```powershell
$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:

```powershell
$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)

```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:

```bash
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)

```bash
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:

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

Optional output path:

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