migration-planlisted
Install: claude install-skill ychampion/ystack
# Migration plan
Code rolls back in a minute. Data, once rewritten, often can't. Plan every data change so that each
step can be deployed alone, can run while old code is still live, and has a way back.
## When it applies
- Any change to a database schema, stored file format, cache layout, queue message shape or index.
- A backfill or bulk rewrite of existing data.
## Procedure
### 1. State the change and the data
Write the before and after shape, how many rows or files are affected (query it), and who reads and
writes this data: services, jobs, other repos, analytics, backups.
### 2. Split into steps that each stand alone
Use expand and contract. A rename of `email` to `contact_email`, for example:
| Step | Change | Old code still works? | Rollback |
| --- | --- | --- | --- |
| 1 Expand | add `contact_email`, nullable | yes | drop the column |
| 2 Dual write | code writes both columns | yes | deploy previous code |
| 3 Backfill | copy `email` to `contact_email` in batches | yes | none needed: old column intact |
| 4 Switch reads | code reads `contact_email` | yes | deploy previous code |
| 5 Contract | stop writing `email`, later drop it | no: point of no return | restore from backup only |
Each step ships separately. Mark the point of no return and put it last, after a waiting period.
### 3. Make the risky steps safe
- **Locks:** know whether the change locks the table on your database and size; use the online or
concurrent form where it exists (adding indexes