migration-safetylisted

# Migration safety ## Treat every environment as production Staging and demo environments hold real data more often than anyone admits, and a migration that destroys data in staging demonstrates that the same operation would run in production. There is no "it's just staging" exception. **Never write a migration that could silently destroy existing data.** ## Destructive operations — stop and surface to the human Do not generate these autonomously. Describe what you intend and why, and wait for confirmation before writing the file: - `DROP TABLE`, `DROP COLUMN`, `TRUNCATE` — destroys rows or values permanently. - `ALTER COLUMN … TYPE` with a lossy cast — the database rewrites the column; values that cannot be cast are lost. - Removing `NOT NULL` and then dropping the column — same as above. - `DELETE FROM` inside a migration — data loss with no recovery short of a backup. ## Safe patterns **Adding a column.** Add it nullable first, even if the final intent is `NOT NULL`. Backfill in a separate migration or deploy step. Add the constraint only after the backfill is confirmed. Three small migrations beat one that rewrites data and adds a constraint at once. **Renaming a column.** Never rename in a single deploy. Expand-contract: add the new column nullable; write to both; backfill new from old; switch reads; drop the old column in a later release once confirmed safe. **Changing a type.** Lossless (`VARCHAR` → `TEXT`) may proceed with a note in the migration comment. L