A database migration may run while old application workers, scheduled jobs or cached code are still active. A change that is valid for the newest code can break an older process during deployment. Backward-compatible migrations reduce this coordination risk.
Expand before contracting
For a rename, add the new column first while keeping the old column. Deploy code that can read both and write both if required. Backfill existing data in bounded batches, verify consistency, then switch reads to the new column. Remove the old column only in a later release after all old code is gone.
Keep migrations bounded
Large table changes can hold locks or consume significant disk and replication capacity. Test against production-like data volume and understand the database version's online DDL behavior. A migration that completes quickly on a small development table may be disruptive in production.
Make data backfills restartable
Use checkpoints or idempotent updates so a failed backfill can resume safely. Monitor progress and errors. Avoid running a huge data transformation inside one transaction if it would create long locks or excessive undo data.
Coordinate deployment order
Document which code version is compatible with each schema state. Ensure rollback plans account for irreversible data transformations; rolling back PHP files does not automatically reverse a database migration.
Checklist
- Use expand, migrate and contract phases.
- Keep old and new code compatible during rollout.
- Backfill data in bounded, restartable batches.
- Test DDL on production-like data.
- Treat schema rollback separately from code rollback.