How to Run Prisma Migrations Without Downtime (Expand-and-Contract Pattern)
Most teams ship Prisma migrations the dangerous way — they run prisma migrate deploy, cross their fingers, and hope nothing breaks. If you're renaming a column, changing a type, or splitting a table, your production app can throw errors mid-deploy.
There's a better way: the expand-and-contract pattern.
The Problem
When you rename a column from username to display_name, Prisma generates a migration that drops the old column and creates a new one. During deployment, any running application code still referencing username will fail.
The Fix: Expand, Migrate, Contract
Step 1 — Expand: Add the new column display_name alongside the old username column. Deploy this migration. Your app still reads from username, so nothing breaks.
Step 2 — Backfill: Copy data from username into display_name. Use a script or a database trigger to keep them in sync during the transition.
Step 3 — Switch: Deploy your application code to read/write from display_name instead of username.
Step 4 — Contract: Once all code references display_name and the backfill is verified, drop the old username column in a final migration.
Why This Works
Each step is independently deployable and reversible. At no point does old code break because of a new schema, and at no point does new code depend on a column that doesn't exist yet.
Key Rule
Never drop a column in the same migration that adds its replacement. Separate the expand and contract into distinct deploys with a code change in between.
This is one of the core patterns I teach in my full course — including shadow databases, safe rollbacks, CI/CD integration, and automating pipelines with Blender Python scripts.