> Postgres: what your AI agent should know — from The Handover, the-handover.org/services/postgres
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

# Postgres

What we tell an AI agent working on a project that uses Postgres: 1 rule, 0 learned the hard way.

Build a full rootnote set for a Postgres project: https://the-handover.org/build?areas=working-agreement,database&database=postgres

Postgres published no file for agents when last checked; this page is the only agent-facing guidance for it we know of.

### 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 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.