13.2.3.5 Migration Rollback Caution

Migration rollback caution addresses the fact that reverting an application's container image to a previous version doesn't automatically undo a database schema migration that the newer version may have already applied, a frequently overlooked complication that can turn a seemingly simple rollback into a broken, inconsistent state.

Why an Image Rollback Alone Can Leave a Mismatched Schema

If the version being rolled back to expects an older schema, but the database has already been migrated forward by the version being rolled back from, the reverted application may now be running against a schema it doesn't actually understand.

kubectl rollout undo deployment/myapp

This command alone reverts the application code, but does nothing about whatever database migration the newer version had already applied — a real risk if that migration changed the schema in a way the older code doesn't expect.

Why Backward-Compatible Migrations Reduce This Risk

Designing migrations to remain compatible with both the old and new application version, at least temporarily, means a rollback doesn't immediately break, even without separately reverting the migration itself.

ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT false;

An additive change like this, which doesn't remove or rename anything the older code depends on, generally remains compatible with both versions during a rollback scenario.

Why Destructive Migrations Are Particularly Risky for Rollback

A migration that drops a column or renames a table the older, rolled-back-to version still depends on creates a much more serious incompatibility that a simple image rollback cannot resolve.

ALTER TABLE users DROP COLUMN legacy_status;

Rolling back the application after this kind of migration has run leaves the older code expecting a column that no longer exists.

Explicitly Including a Migration Rollback Step When Necessary

For a genuinely incompatible migration, the rollback procedure needs to explicitly include reverting that migration, not just the application image.

npm run migrate:down
kubectl rollout undo deployment/myapp

Why Migration Rollback Caution Matters

Recognizing that database migrations and application rollbacks aren't automatically coupled is essential for avoiding a rollback that appears successful at the application layer while leaving the database in a broken, mismatched state.