Manual Down-Migration vs. Version Marking for Failed Upgrade Recovery

The Most Reliable Recovery Approach

When working with databases that lack transactional DDL support (such as MySQL), Manual Rollback is the more reliable approach for ensuring schema integrity. Because non-transactional DDL cannot be rolled back by the database engine, a partial failure leaves the schema in an indeterminate state. Manually reverting the changes ensures the physical schema returns to a known baseline before attempting the upgrade again.

Analysis of Recovery Strategies

Manual Rollback (Recommended)

This involves manually reversing the DDL changes that succeeded before the failure occurred, or restoring a database snapshot. This is the only way to guarantee that the schema is exactly as the migration metadata expects it to be.

• Risk: Depends entirely on the accuracy of the down() method or the freshness of the backup.
• Verification: Requires manual inspection of the table structures to ensure all partial changes are gone.

Version Marking

Using doctrine:migrations:version --add tells Doctrine the migration is complete without actually executing the SQL. This is a metadata-only fix.

• Risk: High. It assumes the partial failure either reached the desired end state or that the missing changes are non-critical.
• Verification: Requires a full schema diff against the expected state.

When Version Marking Introduces Undetectable Drift

Version marking introduces undetectable schema drift when a migration contains multiple DDL statements and fails midway through. Since Doctrine only tracks whether a version was executed—not which specific lines of the up() method succeeded—marking it as executed bypasses all future checks for that version.

Specific conditions for undetectable drift:

• Partial Column Addition: If a migration adds three columns but fails on the third, marking the version as executed leaves the table missing one column. Subsequent migrations that depend on that missing column will fail, but the root cause (the drifted version) remains hidden in the metadata.
• Index/Constraint Failures: If a table is created but the subsequent index creation fails, the application may suffer from severe performance degradation or data integrity issues that no automated migration check will detect.

Recovery Workflow

1. Audit: Check the migration_versions table to confirm the failed version is not listed.
2. Revert: Manually drop any tables or columns created during the failed up() execution.
3. Retry: Fix the underlying cause of the failure and run doctrine:migrations:migrate.

Missing Diagnostic: To refine this recommendation, please specify the database engine (e.g., MySQL 8.0, PostgreSQL 15) and whether the failed migration involved data manipulation (DML) alongside schema changes (DDL).