The pgpg REPL
pgpg is a local PostgreSQL incident simulator. Each scenario boots a real PostgreSQL sandbox in Docker, injects a fault, and hands you a connection string. You drive the whole session from the pgpg REPL.
Launching
Run the binary with no arguments to open the REPL:
pgpg
You land at the base prompt:
pgpg>
From here you load a scenario, ask for help, or quit. The REPL manages the session lifecycle — booting containers, injecting faults, and scoring. It does not run your queries. You investigate the database in a separate psql (or any client) using the connection string each scenario prints.
Commands
| Command | What it does |
|---|---|
start <id> | Boots a real PostgreSQL sandbox in Docker, injects a fault, and prints an incident brief plus a connection string. Enters the scenario. |
hint | Reveals the next progressive hint for the active scenario. Safe to use; tracked alongside your result. |
score | Runs the deterministic, offline scorer and prints a scorecard (Detect / Fix / Trap, total /100) plus a short postmortem. |
reset | Tears the sandbox back down to its injected-fault starting state, discarding your changes. |
stop | Stops and removes the sandbox, leaving the scenario. |
help | Lists commands and usage. |
Scenario IDs look like stage-04/02-name. There are 112 scenarios across 12 tracks.
Starting a scenario
pgpg> start stage-04/02-name
pgpg boots the sandbox, injects the fault, and prints something like:
Incident: queries against app_db have slowed to a crawl since the
last deploy. Connect and find out why.
postgres://postgres:postgres@127.0.0.1:55432/app_db
Copy the connection string into your own client:
psql postgres://postgres:postgres@127.0.0.1:55432/app_db
The scenario prompt
Once a scenario is active, the prompt changes to show which one you are in:
pgpg[scenario]>
This is how you know score, hint, and reset will act on the running incident rather than the base session. The base pgpg> prompt means no scenario is loaded.
Resetting and stopping
If you have changed the database and want a clean slate, reset returns the sandbox to its injected-fault state without re-rolling the scenario. When you are done, stop removes the container:
pgpg[scenario]> stop
pgpg>
Exiting
Leave the REPL with exit or Ctrl-D:
pgpg> exit
Exiting cleans up any running sandbox for you, so you will not leave stray containers behind.