Starting a scenario
Scenarios are the core of pgpg. Each one boots a real, isolated PostgreSQL instance, injects a fault, and challenges you to detect and fix it. There are 112 scenarios across 12 tracks.
Scenario IDs
Every scenario has an ID of the form stage-NN/NN-name, for example:
stage-01/01-missing-index
stage-03/02-lock-contention
The first segment is the track (stage-NN); the second is the scenario within that track.
Starting a scenario
From the REPL, use start with a scenario ID:
pgpg> start stage-01/01-missing-index
When a scenario starts:
- A Docker sandbox boots with a fresh PostgreSQL instance.
- The fault is injected into the database.
- The incident brief is printed, describing the symptoms and any constraints.
- A connection string is printed so you can connect with
psql.
The prompt then changes to show the active scenario:
pgpg[stage-01/01-missing-index]>
Resetting
If your investigation leaves the database in a confusing state — or you simply want a clean slate — use reset to restore the sandbox to its initial broken state:
pgpg[stage-01/01-missing-index]> reset
Sandbox restored to initial state.
The fault is re-injected and the connection string stays valid.
Stopping
When you are done, use stop to tear down the sandbox and free its resources:
pgpg[stage-01/01-missing-index]> stop
Sandbox stopped.
pgpg>
Safe to break
Each scenario runs in its own isolated Docker container against a throwaway database. Nothing touches production, and there is no shared state between scenarios. Drop a table, lock the whole database, or run anything you like — reset brings it back, and stop removes it entirely.