The rillence postgres REPL
Rillence is a local PostgreSQL incident simulator, run via the rillence postgres command. 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 rillence postgres REPL.
Launching
Run the binary with no arguments to open the REPL:
rillence postgres
You land at the base prompt:
postgres>
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 with your usual client — psql, an IDE, or any other — 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 scenarios across the tracks.
Starting a scenario
postgres> start stage-04/02-name
rillence postgres 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:
postgres[scenario]>
This is how you know score, hint, and reset will act on the running incident rather than the base session. The base postgres> 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:
postgres[scenario]> stop
postgres>
Exiting
Leave the REPL with exit or Ctrl-D:
postgres> exit
Exiting cleans up any running sandbox for you, so you will not leave stray containers behind.