Plan Schema Migrations in Stages

A practical approach

Step 1

Add the new field or structure in a way the old application can tolerate. Define how new writes will populate it during the transition.

Step 2

Backfill existing records in controlled batches and verify completeness and correctness. Make the backfill resumable.

Step 3

Switch reads, observe behaviour and only then remove obsolete fields or constraints. Keep a realistic recovery plan for each stage.

Worked example

A profile stores a display name but now needs a separate preferred name. Adding the new field is simple; deciding how existing names should populate it is a product decision. A staged migration can preserve the original while users or an explicit rule provide the new value.

A mistake to avoid

A rollback of application code does not necessarily reverse a destructive data migration. Treat data removal as a separate decision and retain the information needed to recover when appropriate.

Try it yourself

Write a migration plan for renaming a frequently used field. Include the old application’s behaviour, the backfill, the read switch and the point after which rollback becomes more difficult.

Your implementation checklist

• Old and new application versions can coexist.
• Backfills are resumable and checked.
• Read switching is observable.
• Destructive cleanup is delayed until justified.