---
name: migration-safe-rollback
description: Plan schema changes that are safe under traffic and reversible. Use for any risky migration.
---

# Skill: Migration Safe Rollback

## When to use

Column removal/rename, type change, NOT NULL addition, large backfill.

## Expand → Contract (two deploys)

**Removing a column:**

1. Deploy 1: stop reading the column (code change only). Column stays.
2. Verify no reads for a release cycle (logs + metrics).
3. Deploy 2: drop the column.

**Renaming a column:**

1. Add the new column; backfill; write to both.
2. Switch readers to the new column.
3. Drop the old column after a cycle.

**Adding NOT NULL:**

1. Add nullable + default.
2. Backfill in batches (safe under concurrent writes).
3. Add the NOT NULL constraint once fully populated.

## Gotchas

- Prisma has no auto down-migrations — roll **forward** with a new migration.
- Never edit an applied migration.
- Backfills must batch (e.g. 1000 rows/tx) to avoid long locks.
- A code rollback must still work against the new schema — that's why removals are two-deploy.
- Mirror every change in the SQL Server `database/migrations/`.

## Validation

Old code reads new schema; backfill doesn't lock the table; rollback path tested; SQL Server mirror updated.
