Services
Postgres
What we tell an AI agent working on a project that uses Postgres —1 rule.
Build a rootnote set for a Postgres projectPlain text
Postgres did not publish a file for agents when we last checked, so this page is the only agent-facing guidance for it we know of. Why that matters.
Everything here is general guidance: rules an agent knows but does not reliably follow. We have not been caught out by Postgres ourselves, and this page does not pretend otherwise.
Postgres: migrations take locks, and a waiting one queues every query behind it
General guidance · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-19
- Build indexes with
CREATE INDEX CONCURRENTLY on any table with traffic. A
plain one blocks writes for as long as it takes.
- Set a
lock_timeout on migrations, so one waiting for a lock fails fast
instead of queueing every query behind it.
- Check whether a column change rewrites the table before running it on a
large one.
Also applies to every database choice, so it is not repeated here:
- An instruction is not a control: keep production out of the agent's reach, and check recovery yourself
- Never run a migration or a write against production that has not run against a copy
All of it is included when you build a set.