coding-os 0.3.2__py3-none-any.whl

core/skills/db-design/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: db-design
+description: Design and evolve PostgreSQL schemas that survive scale and refactors. Use when modeling a new domain, choosing between normalization and denormalization, designing indexes for known query patterns, writing migrations safely, picking ORM-vs-raw-SQL trade-offs, deciding on soft delete vs hard delete, or evaluating NoSQL document/KV/wide-column for a use case. Targets PostgreSQL 16+ as the default; calls out MongoDB / Redis / DynamoDB where they're the better fit.
+tier: cross-cutting
+domain: [data, backend]
+last_reviewed: "2026-05-11"
+
+---
+
+# Database Design — PostgreSQL First
+
+A practical design playbook for the project's stack: PostgreSQL as the system of record, accessed by the Go+Fiber business core and the Python+FastAPI AI adapter, with hexagonal repositories isolating the rest of the codebase from schema specifics.
+
+## When to Use This Skill
+
+- Modeling the schema for a new bounded context (orders, users, lessons, payments).
+- Adding a column or table that will see growth.
+- Choosing PK / FK shapes (UUID? bigint? prefixed string?).
+- Designing indexes after seeing query patterns or EXPLAIN output.
+- Writing migrations that touch live data (never just on a fresh DB).
+- Picking ORM (sqlc / GORM / SQLAlchemy / Drizzle) vs raw SQL for a feature.
+- Deciding on soft delete vs hard delete + audit table.
+- Evaluating Redis (cache/queue) vs Postgres (LISTEN/NOTIFY, advisory locks) for a side-channel.
+
+Skip when: prototyping with a sqlite that will be thrown away. Use this skill before the throw-away gets promoted.
+
+## The Three Rules
+
+1. **Constraints in the database, not the application.** `NOT NULL`, `CHECK`, `UNIQUE`, `FOREIGN KEY` enforced by Postgres survive bugs in the app, replays of stale code, and direct DBA fixes. Application-only invariants are constantly violated by accident.
+2. **Migrations are forward-only and additive.** Never drop a column the same release you stop writing to it. Two-phase: stop writing → wait → drop. See [references/migration-discipline.md](references/migration-discipline.md).
+3. **Your queries determine your indexes, not the other way around.** Don't index speculatively; index after you see EXPLAIN output for the queries that matter.
+
+## Modeling Choices
+
+### Primary Keys
+
+| Style | Pros | Cons | Use when |
+|---|---|---|---|
+| **bigint identity** | Compact, sequential, fast B-tree, predictable | Leaks count, predictable, one-DB-only | Internal high-volume tables (audit log, events). |
+| **UUID v7** (time-ordered) | Globally unique, mergeable, sortable | 16 bytes, slightly bigger indexes | Default for user-visible entities. Postgres 18 has built-in `uuidv7()`; on 16/17 use `pg_uuidv7` extension or app-side. |
+| **UUID v4** (random) | Globally unique, no info leakage | Index bloat from random insertion order, 4× page splits vs v7 | Avoid for primary keys at scale. Fine for IDs that never get indexed. |
+| **Prefixed text** (`ord_8h2k4n9d3p7q`) | Self-documenting in logs, debug-friendly | App-side ID generation, slightly larger | Public API surface (Stripe pattern). Pair with a UUID v7 internally if needed. |
+
+**Default for this project**: prefixed text IDs (`usr_`, `ord_`, `lsn_`, `pay_`) generated app-side from UUID v7 + base32. Internally, the column is `TEXT NOT NULL PRIMARY KEY`. Postgres handles text PKs well at this size.
+
+### Foreign Keys
+
+ALWAYS declare them. ALWAYS index them.
+
+```sql
+-- Postgres does NOT auto-index foreign key columns. Forgetting this
+-- is the #1 cause of slow DELETE / UPDATE on the parent table.
+CREATE TABLE order_items (
+    id          TEXT       PRIMARY KEY,
+    order_id    TEXT       NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
+    sku         TEXT       NOT NULL,
+    quantity    INT        NOT NULL CHECK (quantity > 0),
+    UNIQUE (order_id, sku)
+);
+
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+```
+
+Cascade rules — pick deliberately:
+
+- `ON DELETE CASCADE` — the child has no meaning without the parent (line items without an order).
+- `ON DELETE RESTRICT` — refuse the delete if children exist (default; force the app to clean up).
+- `ON DELETE SET NULL` — the FK is optional; preserve the child (e.g., assigned-by user gets nulled on user delete).
+
+### Nullability
+
+Default: `NOT NULL` on every column. Add nullability only with a written reason. `NULL` means "we don't know" — distinct from "we know it's absent" (use a sentinel or separate flag).
+
+Common mistakes: `email VARCHAR(255)` nullable when "user without email" is impossible → fix data + make it `NOT NULL`.
+
+### Time Columns
+
+```sql
+created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+deleted_at  TIMESTAMPTZ,                      -- soft delete (see below)
+```
+
+- ALWAYS `TIMESTAMPTZ`, never `TIMESTAMP` (without TZ). The latter loses information at the boundary and bites you in 3 years.
+- Update `updated_at` via trigger so app bugs can't forget:
+  ```sql
+  CREATE OR REPLACE FUNCTION set_updated_at() RETURNS trigger AS $$
+  BEGIN NEW.updated_at = NOW(); RETURN NEW; END;
+  $$ LANGUAGE plpgsql;
+
+  CREATE TRIGGER orders_set_updated_at BEFORE UPDATE ON orders
+      FOR EACH ROW EXECUTE FUNCTION set_updated_at();
+  ```
+
+### Soft Delete vs Hard Delete
+
+Soft delete (`deleted_at TIMESTAMPTZ`) when:
+
+- Compliance / audit requires keeping records.
+- Users can "undo" deletes within a window.
+- Foreign-key cleanup is impractical.
+
+Hard delete when:
+
+- GDPR right-to-be-forgotten kicks in.
+- Storage cost > legal/business value.
+- The data was always ephemeral (sessions, OTPs).
+
+**Soft delete pitfalls**:
+
+- Every query needs `WHERE deleted_at IS NULL` — easy to forget. Mitigate with a view: `CREATE VIEW active_orders AS SELECT * FROM orders WHERE deleted_at IS NULL;` and treat the view as the default.
+- Unique constraints break: `UNIQUE(email)` on a soft-deleted row blocks re-registration. Use `UNIQUE(email) WHERE deleted_at IS NULL` (partial unique index).
+
+```sql
+CREATE UNIQUE INDEX users_email_active_unique
+    ON users(email) WHERE deleted_at IS NULL;
+```
+
+### Money
+
+```sql
+amount       BIGINT      NOT NULL,           -- minor units (cents)
+currency     CHAR(3)     NOT NULL,           -- ISO 4217: USD, EUR, IRR
+CHECK (amount >= 0 OR allow_negative)
+```
+
+NEVER use `FLOAT` / `REAL` / `DOUBLE PRECISION` for money. NEVER use `NUMERIC` without a written reason (slow + complex; integer cents covers 99% of cases).
+
+For exotic currencies (JPY has no minor unit; KWD has 3 digits), store the actual minor-unit count and document per-currency multiplication factor in app code.
+
+### Enums vs Lookup Tables vs CHECK
+
+Three options for "status" columns:
+
+```sql
+-- (a) Postgres native ENUM — compact, fast, hard to evolve
+CREATE TYPE order_status AS ENUM ('pending', 'paid', 'shipped', 'cancelled');
+
+-- (b) CHECK constraint with TEXT — flexible, slightly bigger
+status TEXT NOT NULL CHECK (status IN ('pending', 'paid', 'shipped', 'cancelled'))
+
+-- (c) Lookup table with FK — most flexible, joins required
+status_id INT NOT NULL REFERENCES order_statuses(id)
+```
+
+**Rule of thumb**:
+
+- **(b) CHECK + TEXT** is the right default. Easy to add values (just update the constraint), readable in queries, doesn't need joins.
+- **(a) ENUM** when set is truly fixed and shows up in millions of rows.
+- **(c) Lookup table** when the set has metadata (label, color, ordering) the app needs to render.
+
+Avoid mixing: pick one per concept project-wide.
+
+### JSON Columns
+
+Postgres `JSONB` is genuinely useful for:
+
+- **Settings / preferences** with no fixed schema and no querying needs.
+- **Webhook payloads** archived for replay / debugging.
+- **Polymorphic event bodies** in an event-store table.
+
+NOT for:
+
+- Anything you'll filter on frequently. Use a real column.
+- Anything with a stable schema. That's just a table — make it one.
+- Money. Always real columns.
+
+If you must filter on JSONB, add a GIN index:
+
+```sql
+CREATE INDEX idx_orders_meta_gin ON orders USING GIN (metadata jsonb_path_ops);
+-- Use jsonb_path_ops for ?, ?| , ?& operators (smaller index than the default).
+```
+
+### Polymorphic Associations — Don't
+
+```sql
+-- ANTI-PATTERN: comments table polymorphic on (target_type, target_id)
+CREATE TABLE comments (
+    target_type TEXT,  -- 'post' | 'video' | 'order'
+    target_id   TEXT,
+    body        TEXT,
+    -- impossible to FK; impossible to JOIN cleanly
+);
+```
+
+Replace with separate tables: `post_comments`, `video_comments`, `order_comments`. Yes, more tables. Yes, real FKs work. Yes, this pays off.
+
+If the polymorphism is genuine (any user-content can be commented on), use `comments` + a `comment_targets` join table per target type, all with proper FKs.
+
+## Indexing Strategy
+
+### Read the Query First
+
+Don't index speculatively. Find the slow query, run `EXPLAIN (ANALYZE, BUFFERS)`, see the plan, then add the index.
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT id, total FROM orders
+WHERE user_id = $1 AND status = 'paid'
+ORDER BY created_at DESC LIMIT 20;
+
+-- Look for:
+--   "Seq Scan on orders" → missing index
+--   "Rows Removed by Filter: <high>" → wrong index
+--   "Sort Method: external merge" → spilling to disk; add index that satisfies ORDER BY
+```
+
+### Index Types
+
+| Type | Use for |
+|---|---|
+| **B-tree** (default) | Equality + range + ORDER BY. Most common. |
+| **Hash** | Equality only; rarely worth it (B-tree is fine). |
+| **GIN** | Full-text, JSONB, arrays — "contains" semantics. |
+| **GiST** | Geometric, ranges, full-text (older). |
+| **BRIN** | Huge append-only tables sorted by insertion (audit logs, time-series). 1000× smaller than B-tree. |
+
+### Composite Indexes — Order Matters
+
+Match the WHERE + ORDER BY of your query. The leftmost columns are usable for partial matches; rightward columns are not.
+
+```sql
+-- Query: WHERE user_id = $1 AND status = 'paid' ORDER BY created_at DESC
+CREATE INDEX idx_orders_user_status_created
+    ON orders(user_id, status, created_at DESC);
+-- Order: equality cols first, then range/ORDER BY col last.
+```
+
+### Partial Indexes
+
+Index only rows that matter. Massive size reduction for "active" / "pending" subsets.
+
+```sql
+-- Common: only paid orders — most queries filter on this.
+CREATE INDEX idx_orders_paid_user
+    ON orders(user_id, created_at DESC)
+    WHERE status = 'paid';
+
+-- Common: only undeleted rows.
+CREATE INDEX idx_users_email_active
+    ON users(email) WHERE deleted_at IS NULL;
+```
+
+### Covering Indexes (INCLUDE)
+
+When your query selects 2 small columns and filters on a 3rd, INCLUDE lets the index satisfy the query without a heap fetch.
+
+```sql
+CREATE INDEX idx_orders_user_paid_covering
+    ON orders(user_id) INCLUDE (id, total)
+    WHERE status = 'paid';
+```
+
+### What Not to Index
+
+- Columns with low cardinality (`is_active` boolean) — usually a partial index on the rare value works.
+- Columns rarely filtered on.
+- Tables that are 99% writes, 1% reads (background queues, audit append).
+- Anything you can't see used in `pg_stat_user_indexes` after a week — drop it.
+
+### Maintenance
+
+```sql
+-- Weekly:
+SELECT schemaname, relname, indexrelname, idx_scan, idx_tup_read, idx_tup_fetch
+FROM pg_stat_user_indexes
+ORDER BY idx_scan ASC;
+-- Drop indexes with idx_scan = 0 after a full week of normal traffic.
+
+-- VACUUM + ANALYZE on a regular schedule (autovacuum usually fine; tune
+-- per-table for very-large or hot tables).
+```
+
+For the full migration playbook (online additive changes, expand-contract, backfills, NOT NULL adds, FK adds), see [references/migration-discipline.md](references/migration-discipline.md).
+
+For Postgres-specific patterns (advisory locks, LISTEN/NOTIFY, full-text search, pgvector for embeddings, partitioning), see [references/postgres-patterns.md](references/postgres-patterns.md).
+
+## ORM vs Raw SQL Trade-Off
+
+Pick per-query, not per-codebase:
+
+| Use ORM (sqlc / SQLAlchemy / Drizzle / GORM) when | Use raw SQL when |
+|---|---|
+| CRUD on a single row by PK | Multi-table joins with non-trivial filters |
+| Simple list with 1–2 filters | Aggregations, window functions, CTEs |
+| Inserts / updates with all columns | Bulk operations (`COPY`, `INSERT ... SELECT`) |
+| Mocking is critical (test isolation) | EXPLAIN-tuned hot paths |
+| Code-generated typed clients available | Anything where you'd write SQL anyway, then translate to ORM |
+
+**This project**: in Go, `sqlc` (compile-time SQL→typed Go) for everything except trivial CRUD. In Python, `asyncpg` + thin handcrafted queries; SQLAlchemy Core (NOT ORM) when you need composable query building. Avoid ActiveRecord-style ORM (Django ORM, GORM eager loading, SQLAlchemy ORM) — they hide the actual queries until prod.
+
+## N+1 Detection
+
+The single most common performance bug. Detect via:
+
+1. **Logging**: log every query with timing. `SELECT * FROM orders WHERE id = X` repeated 100 times = N+1.
+2. **Linting**: `pg_qualstats` extension flags hot patterns.
+3. **Test assertion**: `assert query_count(do_thing) <= 5`. Fails the build when N+1 sneaks in.
+
+Fix:
+
+- ORM: eager load (`prefetch_related`, `joinedload`, `JOIN FETCH`, `Includes`).
+- Raw SQL: `JOIN` or `WITH ... SELECT ... FROM unnest($1)` for batch lookups.
+
+## Connection Pool Sanity
+
+```
+PgBouncer (transaction mode) → Postgres
+  ↑
+  Application pool (sqlc / asyncpg) — small (10–20 conns per replica)
+```
+
+Rules:
+
+- App pool max ≪ Postgres `max_connections`. With PgBouncer in front, you can have 1000 app connections multiplexed onto 50 actual Postgres conns.
+- Idle timeout < server idle-in-transaction timeout. Avoid orphaned transactions.
+- Per-tenant pool? No. Use one pool, set search_path / RLS policy per request.
+
+## Source Material
+
+- *PostgreSQL Documentation* (16/17/18) — the only canonical source for Postgres specifics. Don't trust Stack Overflow for performance; do trust the docs.
+- *Designing Data-Intensive Applications* (Kleppmann) — the storage-and-retrieval chapters are timeless.
+- *The Art of PostgreSQL* (Dimitri Fontaine) — practical Postgres patterns.
+- Markus Winand — *use-the-index-luke.com* — definitive index reference.
+- Brandur Leach — schema migration write-ups (heroku/stripe era).
+- Sidekiq author Mike Perham — background-job patterns leveraging Postgres LISTEN/NOTIFY.

core/skills/db-design/assets/migration-template.sql

@@ -0,0 +1,49 @@
+-- migrations/NNN_<short_description>.sql
+-- ---------------------------------------------------------------------
+-- Migration template — copy this when authoring a new schema change.
+--
+-- Phase: <expand | migrate | contract>
+-- Backward compatible with previous release: <yes | no, blocker: ...>
+-- Lock duration estimate: <e.g., <100ms ACCESS EXCLUSIVE>
+-- Rewrites table: <yes | no>
+-- Backfill: <none | inline | background-job NAME>
+-- Rollback path: <new migration NNN+k that reverses>
+-- ---------------------------------------------------------------------
+
+-- Fail fast if we cannot acquire locks promptly.
+SET LOCK_TIMEOUT = '5s';
+SET STATEMENT_TIMEOUT = '60s';
+
+BEGIN;
+
+-- ============================================================
+-- 1. SCHEMA CHANGES (DDL) — keep each statement short
+-- ============================================================
+
+-- Example: add a new column (instant on PG 11+ with constant default).
+ALTER TABLE orders
+    ADD COLUMN coupon_code TEXT;
+
+-- Example: add NOT VALID constraint (no full-table scan now).
+-- ALTER TABLE orders
+--     ADD CONSTRAINT orders_coupon_format
+--     CHECK (coupon_code ~ '^[A-Z0-9]{4,16}$') NOT VALID;
+
+-- ============================================================
+-- 2. NEW INDEXES (must be CONCURRENTLY, NOT inside transaction)
+-- ============================================================
+-- IMPORTANT: CREATE INDEX CONCURRENTLY cannot run inside BEGIN.
+-- Some migration runners (sqitch, dbmate) support marking a migration as
+-- "no-transaction" — use that flag and put concurrent ops in a separate
+-- migration file.
+
+-- See: migrations/NNN+1_create_idx_orders_coupon_code.sql
+
+COMMIT;
+
+-- ============================================================
+-- 3. POST-DEPLOY (separate migration file, after app rolls out)
+-- ============================================================
+--   - Validate constraints: ALTER TABLE ... VALIDATE CONSTRAINT ...
+--   - Drop old columns (only after a full deploy soak)
+--   - Backfill (separate background job, not inline DDL)

core/skills/db-design/references/migration-discipline.md

@@ -0,0 +1,290 @@
+# Migration Discipline — Zero-Downtime Schema Changes
+
+The patterns for changing schema on a live database. Every migration here assumes:
+
+1. Multiple app replicas running.
+2. App version N and N+1 may run simultaneously during deploy.
+3. You cannot pause writes.
+4. Postgres ≥ 13 (most patterns work back to 9.6).
+
+If you have downtime windows, you can skip half the dance. Document explicitly when an `ACCESS EXCLUSIVE LOCK` operation is acceptable.
+
+## The Two Laws
+
+1. **Forward only.** Migrations don't have a `down()`. Mistakes are fixed by writing a NEW migration that undoes the change. Reversibility encourages laziness; forward-only forces care.
+2. **Each release is backward-compatible with the previous one.** App N+1 can run against the old schema. App N can run against the new schema. NEVER both directions broken at once.
+
+## Expand-Contract — the Universal Pattern
+
+Most schema changes follow this three-phase release cycle:
+
+```
+Release 1: EXPAND
+  - Add new schema (column / table / index) without removing old.
+  - App N still uses old; app N+1 (rolled out next) writes BOTH old + new.
+
+Release 2: MIGRATE
+  - Backfill data from old → new.
+  - App writes both, reads from new (fall back to old if absent).
+
+Release 3: CONTRACT
+  - Stop writing to old.
+  - Drop old column / table / index after a soak period.
+```
+
+Three releases for a rename. Yes, really. Examples below.
+
+## Adding a Column — Easy
+
+Postgres ≥ 11 with no DEFAULT or with a constant DEFAULT: instant. No table rewrite.
+
+```sql
+-- Migration v42 — INSTANT, no lock.
+ALTER TABLE orders ADD COLUMN coupon_code TEXT;
+
+-- With a constant default (PG 11+) — also INSTANT.
+ALTER TABLE orders ADD COLUMN priority SMALLINT NOT NULL DEFAULT 5;
+```
+
+⚠️ Volatile DEFAULT (e.g., `NOW()`, function call) DOES rewrite. Use a backfill instead.
+
+## Adding NOT NULL to Existing Column — 3-Phase
+
+Cannot just `ALTER COLUMN ... SET NOT NULL` on a populated nullable column without scanning the whole table.
+
+```sql
+-- Phase 1 (release 1): app starts writing the value.
+-- Schema unchanged.
+
+-- Phase 2 (release 2): backfill in batches OFFLINE or via background job.
+UPDATE orders SET status = 'pending' WHERE status IS NULL;
+
+-- Phase 3 (release 3): now safe to constrain.
+-- Use NOT VALID to skip the full-table check at the lock-acquisition moment:
+ALTER TABLE orders
+    ADD CONSTRAINT orders_status_not_null CHECK (status IS NOT NULL) NOT VALID;
+ALTER TABLE orders VALIDATE CONSTRAINT orders_status_not_null;
+-- VALIDATE acquires a SHARE UPDATE EXCLUSIVE lock — readers + writers continue.
+
+-- Optional cleanup (release 4): convert CHECK → NOT NULL.
+ALTER TABLE orders ALTER COLUMN status SET NOT NULL;
+ALTER TABLE orders DROP CONSTRAINT orders_status_not_null;
+-- The SET NOT NULL above is now FAST because PG sees the validated CHECK.
+```
+
+## Adding a Foreign Key — 2-Phase
+
+```sql
+-- Phase 1: add the FK as NOT VALID. Doesn't lock-scan the whole table.
+ALTER TABLE order_items
+    ADD CONSTRAINT order_items_order_id_fk
+    FOREIGN KEY (order_id) REFERENCES orders(id) NOT VALID;
+
+-- Phase 2: validate later (separate migration / background).
+ALTER TABLE order_items VALIDATE CONSTRAINT order_items_order_id_fk;
+```
+
+## Adding an Index — Always CONCURRENTLY
+
+```sql
+-- WRONG — locks writes for minutes on a big table.
+CREATE INDEX idx_orders_user ON orders(user_id);
+
+-- RIGHT — no write block, scans + builds in background.
+CREATE INDEX CONCURRENTLY idx_orders_user ON orders(user_id);
+```
+
+Caveats:
+
+- `CONCURRENTLY` cannot run inside a transaction. If your migration framework wraps each migration in a tx, escape it (e.g., Alembic: `with op.get_context().autocommit_block(): op.execute(...)`)
+- Failed concurrent build leaves an INVALID index. Drop and retry: `DROP INDEX CONCURRENTLY IF EXISTS idx_name;`
+
+## Renaming a Column — 3-Phase
+
+```sql
+-- Release 1: ADD NEW COLUMN, dual-write.
+ALTER TABLE users ADD COLUMN full_name TEXT;
+-- App writes BOTH `name` and `full_name`. Reads from `name`.
+
+-- Release 2: BACKFILL + READ from new.
+UPDATE users SET full_name = name WHERE full_name IS NULL;
+-- App reads `full_name`, falls back to `name` if NULL.
+-- App still writes both.
+
+-- Release 3: STOP writing old.
+-- App writes only `full_name`. Reads only `full_name`.
+
+-- Release 4: DROP old column.
+ALTER TABLE users DROP COLUMN name;
+```
+
+Same pattern for renaming a table — three releases at minimum.
+
+## Renaming a Table — 3-Phase via View
+
+Faster alternative:
+
+```sql
+-- Release 1: rename + create a view at the old name.
+ALTER TABLE legacy_users RENAME TO users;
+CREATE VIEW legacy_users AS SELECT * FROM users;
+
+-- Release 2: app updated to use new name.
+
+-- Release 3: drop the view.
+DROP VIEW legacy_users;
+```
+
+The view is updatable for simple cases. Stops working for complex queries; test thoroughly.
+
+## Dropping a Column — 2-Phase
+
+```sql
+-- Release 1: app stops reading + writing the column.
+
+-- Release 2 (after a soak period — at least one full deploy + observation):
+ALTER TABLE orders DROP COLUMN deprecated_status;
+```
+
+Postgres 11+ marks the column as dropped without rewriting the table; rewrite happens at the next `VACUUM FULL` or `pg_repack`.
+
+## Dropping an Index — Always CONCURRENTLY
+
+```sql
+DROP INDEX CONCURRENTLY IF EXISTS idx_orders_old;
+```
+
+## Backfills — Batch It
+
+Never run a single `UPDATE` over a billion-row table. The undo log explodes; replicas lag; vacuum can't keep up.
+
+```sql
+-- Migration runner: kick off background job, NOT inline.
+
+-- Background worker, in batches of 10k:
+DO $$
+DECLARE
+  rows_updated INT := 1;
+BEGIN
+  WHILE rows_updated > 0 LOOP
+    WITH batch AS (
+      SELECT id FROM orders
+      WHERE coupon_code IS NULL
+      LIMIT 10000
+      FOR UPDATE SKIP LOCKED
+    )
+    UPDATE orders o
+    SET coupon_code = COALESCE(o.legacy_promo, '')
+    FROM batch
+    WHERE o.id = batch.id;
+
+    GET DIAGNOSTICS rows_updated = ROW_COUNT;
+    PERFORM pg_sleep(0.1);  -- breathe; let replication catch up
+  END LOOP;
+END $$;
+```
+
+For backfills measured in millions of rows, prefer a dedicated CLI command + checkpoint table that records progress, so re-running picks up where it left off.
+
+## Type Changes — Almost Always Add-and-Migrate
+
+Changing `INT` → `BIGINT` on a wide table rewrites everything. Don't.
+
+Pattern:
+
+```sql
+-- Phase 1: add new column with the new type.
+ALTER TABLE events ADD COLUMN id_v2 BIGINT;
+-- App dual-writes id and id_v2.
+
+-- Phase 2: backfill.
+UPDATE events SET id_v2 = id::bigint WHERE id_v2 IS NULL;
+
+-- Phase 3: switch FK targets to id_v2 (per related table).
+-- Phase 4: drop id, rename id_v2 → id.
+```
+
+## Locking Behavior Cheat Sheet
+
+| Operation | Lock acquired | Blocks |
+|---|---|---|
+| `ADD COLUMN` (no default or constant default) | `ACCESS EXCLUSIVE` for milliseconds | Everything briefly |
+| `ADD COLUMN` (volatile default) | `ACCESS EXCLUSIVE` for table rewrite | Everything for minutes |
+| `ALTER COLUMN ... SET NOT NULL` (without prior CHECK) | `ACCESS EXCLUSIVE` for full scan | Everything |
+| `ALTER COLUMN ... SET NOT NULL` (with validated CHECK) | `ACCESS EXCLUSIVE` for milliseconds | Briefly |
+| `ADD CONSTRAINT ... NOT VALID` | `ACCESS EXCLUSIVE` for milliseconds | Briefly |
+| `VALIDATE CONSTRAINT` | `SHARE UPDATE EXCLUSIVE` | DDL only |
+| `CREATE INDEX` | `SHARE` | Writes |
+| `CREATE INDEX CONCURRENTLY` | `SHARE UPDATE EXCLUSIVE` | DDL only |
+| `DROP COLUMN` | `ACCESS EXCLUSIVE` for milliseconds | Briefly |
+| `DROP INDEX` | `ACCESS EXCLUSIVE` for milliseconds | Briefly |
+| `DROP INDEX CONCURRENTLY` | `SHARE UPDATE EXCLUSIVE` | DDL only |
+| `ALTER TABLE ... RENAME` | `ACCESS EXCLUSIVE` for milliseconds | Briefly |
+| `TRUNCATE` | `ACCESS EXCLUSIVE` | Everything |
+
+The dangerous ones are the `ACCESS EXCLUSIVE for ... full scan / rewrite` rows. Those are the ones you must dance around.
+
+## Migration Tooling Conventions
+
+Whatever tool you use (Goose, Atlas, Alembic, Flyway, dbmate, sqitch), establish:
+
+1. **One migration per file**, named `NNN_description.sql` (NNN monotonic).
+2. **Migrations are append-only** — never edit an applied migration. Mistake → write a new one that fixes it.
+3. **Schema dump checked in** — run `pg_dump --schema-only --no-owner` after each migration; commit. PR review then sees the actual end state, not just the diff.
+4. **Migrations applied in CI** — every PR runs `migrate up` against a fresh DB. If it fails, build fails.
+5. **`SET LOCK_TIMEOUT` on every migration** — fail fast if you can't acquire the lock:
+   ```sql
+   SET LOCK_TIMEOUT = '5s';
+   SET STATEMENT_TIMEOUT = '60s';
+
+   ALTER TABLE orders ADD COLUMN coupon_code TEXT;
+   ```
+6. **Migrations are idempotent where possible**: `CREATE INDEX IF NOT EXISTS`, `ALTER TABLE ... IF NOT EXISTS COLUMN`, `DROP IF EXISTS`. Re-running a failed migration shouldn't error.
+
+## Per-PR Checklist
+
+Before approving a migration PR, the reviewer asks:
+
+- [ ] Lock duration: which lock, on which tables, for how long?
+- [ ] Table rewrite: yes/no? If yes, scheduled for off-hours?
+- [ ] Backfill: inline vs background job? Batched? Idempotent? Recoverable?
+- [ ] App compatibility: does the previous release still work after this migration applies?
+- [ ] Rollback plan: what's the new migration we'd write if this one is wrong?
+- [ ] Index added concurrently? Index removed concurrently?
+- [ ] `LOCK_TIMEOUT` set?
+- [ ] Tested on prod-sized dataset (or at least same shape)?
+
+A "no" without a written justification = block.
+
+## Postgres-Specific Gotchas
+
+- **`SERIAL` columns implicitly create a sequence + DEFAULT + UNIQUE**. Modern code uses `GENERATED BY DEFAULT AS IDENTITY` (cleaner, owns the sequence properly).
+- **`CITEXT`** for case-insensitive text is fine but breaks the GIN index pattern. Consider lowercasing in the column itself with a generated column.
+- **Generated columns** (`GENERATED ALWAYS AS ... STORED`) are cheap and let you index a derived value. Use for `lower(email)`, JSON extracts, etc.
+- **`pg_repack` / `pg_squeeze`** for online table rewrite when you absolutely must. Better than `VACUUM FULL` (which locks).
+- **Replication lag**: most patterns assume primary-replica setup. If a backfill is heavy, throttle it (the `pg_sleep(0.1)` above) and watch `pg_stat_replication`.
+
+## Anti-Patterns
+
+1. **Editing a previously applied migration**. Now app version on prod and dev have different schema histories. Tools detect this and refuse to run.
+2. **Single-step rename / type change**. Always 3-phase.
+3. **`ACCESS EXCLUSIVE` operation in a long transaction**. Holds the lock for the entire transaction. Always one statement per migration when locking.
+4. **DEFAULT value backfill via `UPDATE ... WHERE col IS NULL`** on a live large table. Batch + sleep, or use a separate background job.
+5. **Concurrent index without `IF NOT EXISTS`** then re-running after failure. Picks up the old INVALID index — drop first.
+6. **No `LOCK_TIMEOUT`**. The migration hangs forever waiting for a long-running query, blocking everything new. Always 5–10s default.
+
+## Rollback Reality Check
+
+You don't have one. The "rollback" is "write another migration that undoes". Plan migrations so this is possible:
+
+- Don't `DROP COLUMN` until the column has been unused for a full deploy cycle. The "undo" of a drop is the data — gone.
+- Rename via add-and-deprecate, not via in-place rename.
+- Test the new code with the OLD schema (CI step: deploy app version N+1 against schema version N). Catches "I forgot to roll out the migration first" bugs.
+
+## References
+
+- [PostgreSQL "Strong Consistency, No SQL" — locking patterns](https://www.postgresql.org/docs/current/explicit-locking.html)
+- [Strong's blog — *Safer Postgres migrations*](https://www.thatguyfromdelhi.com/2024/03/safer-postgres-migrations.html)
+- [GitLab — *Avoid downtime in migrations*](https://docs.gitlab.com/ee/development/migration_style_guide.html)
+- [Stripe — *Online migrations at scale*](https://stripe.com/blog/online-migrations) — the canonical write-up.
+- `lock_timeout` reference: <https://www.postgresql.org/docs/current/runtime-config-client.html>