Question
Why does schema migration fail?
Quick Answer
Updating the schema in your head while leaving the downstream systems untouched. You'll notice this when your new understanding keeps colliding with your old behavior — you believe in delegation but still review every pull request, you believe in rest but still feel guilty on weekends. The belief.
The most common reason schema migration fails: Updating the schema in your head while leaving the downstream systems untouched. You'll notice this when your new understanding keeps colliding with your old behavior — you believe in delegation but still review every pull request, you believe in rest but still feel guilty on weekends. The belief migrated. The infrastructure didn't.
The fix: Pick one belief or mental model you've updated in the last year. Write it down as 'Old schema: X → New schema: Y.' Then list every decision, habit, relationship, or system that was built on the old schema. For each one, mark it: already migrated, needs migration, or can't migrate yet. You now have a migration plan.
The underlying principle is straightforward: When you update a schema you must also update everything built on top of it.
Learn more in these lessons