Skip to content
Database

PostgreSQL

Official site

Playbooks for PostgreSQL

  1. Diagnosing and handling Postgres serialization failures (40001)

    Covers confirming this is a genuine repeatable-read/serializable conflict and adding the application-level retry that Postgres's own documentation prescribes. It does not cover deadlocks (SQLSTATE 40P01 — a different mechanism entirely, see the deadlock playbook) and does not attempt to tune away contention at the schema level.

    Unverifiedno reproductions yetWhy this confidence?

  2. Diagnosing Postgres connection exhaustion (too many clients already)

    Covers the shortest path to confirming you're actually out of connections, finding who's holding them, and the immediate relief versus durable fix. Does not cover PgBouncer's own client-limit error (see the PgBouncer playbook) or ORM/driver-specific pool leaks beyond pointing at the node-postgres playbooks that cover them in depth.

    Unverifiedno reproductions yetWhy this confidence?

  3. Diagnosing and preventing Postgres deadlocks (40P01)

    Covers reading the log detail Postgres already wrote, identifying the lock-ordering mismatch, and enforcing a consistent order. Does not cover SQLSTATE 40001 serialization failures — a different SQLSTATE and a different mechanism entirely, with its own playbook — and does not cover finding a leak; a deadlock always resolves itself within about a second whether or not anyone looks at it.

    Unverifiedno reproductions yetWhy this confidence?

  4. Fixing 'prepared statement does not exist' under PgBouncer transaction pooling

    Covers the PgBouncer-side mechanism and its two fixes: native prepared-statement tracking (1.21+) or avoiding named server-side prepared statements. Does not cover postgres.js's mirror-image 'already exists' error, which shares the same underlying incompatibility but needs a client-side fix, not a PgBouncer-side one — see the postgres.js playbook, which is not interchangeable with this one despite the similar wording.

    Unverifiedno reproductions yetWhy this confidence?

  5. Handling Prisma P2002 unique constraint violations

    Covers recognising that P2002 is Postgres's unique constraint doing its job, correctly, and the two idiomatic ways to handle an expected duplicate. Does not cover tracing where an unexpected duplicate came from (a retry without an idempotency key, a double-fired webhook, a bad backfill) — this playbook only gets you to recognising which situation you're in.

    Unverifiedno reproductions yetWhy this confidence?

  6. Diagnosing a Supabase RLS INSERT rejection

    Covers confirming which policies exist and why WITH CHECK is rejecting the row, and adding a correct INSERT policy. Does not cover RLS for SELECT/UPDATE/DELETE (governed by USING, a different clause) or auth/JWT configuration beyond noting that the SQL editor bypasses RLS entirely and so can never be used to test a policy.

    Unverifiedno reproductions yetWhy this confidence?

Versions