Quick start
This is the 60-second path from a fresh install to your first scored incident. You will boot a sandbox, investigate a real PostgreSQL fault, fix it, and score your work.
1. Open the REPL
Make sure Docker is running, then launch the pgpg REPL:
pgpg
2. Start a scenario
Inside the REPL, start the first scenario. pgpg boots an isolated Docker sandbox, injects the fault, prints an incident brief, and prints a connection string:
pgpg> start stage-01/01-missing-index
Booting sandbox... ready.
Brief: The orders API is timing out. A frequent lookup query
has degraded to a sequential scan under load. Restore acceptable
latency without altering the query.
Connect: postgres://postgres:postgres@127.0.0.1:55432/app_db
pgpg[stage-01/01-missing-index]>
3. Investigate
In another terminal, connect with the printed connection string and dig into the database with real psql:
psql "postgres://postgres:postgres@127.0.0.1:55432/app_db"
EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = 42;
The plan reveals a sequential scan on a large table — no index supports the lookup.
4. Apply a fix
CREATE INDEX idx_orders_customer_id ON orders (customer_id);
5. Score
Back in the pgpg REPL, run score. Scoring is deterministic and offline — no AI is involved:
pgpg[stage-01/01-missing-index]> score
Detect ... 30/30
Fix ...... 45/50
Trap ..... 20/20
Total .... 95/100
The Detect / Fix / Trap breakdown rewards identifying the root cause, applying a correct fix, and avoiding traps (such as changing the query when you were asked not to).
Next steps
Stuck on a scenario? Run hint inside the REPL for progressive hints. When you are ready to explore the full catalog of incidents, see the Incident tracks page.