After a failed Composer upgrade, should a Symfony app roll back database migrations or just restore composer.lock and clear the cache?

Short answer

Restoring composer.lock and clearing var/cache is always required, but it is never sufficient on its own once migrations have executed. Those steps restore code and the compiled container; they do nothing to the database. Whether you then roll back migrations or restore a database snapshot depends on one thing: whether the migrations that ran are cleanly reversible.

The decision point

There is no single documented rule, but the practical decision point is the reversibility of the executed migrations:

• Rollback is safe when every executed migration has a complete down() method, contains no irreversible operations (raw SQL data changes, dropped columns with data, destructive updates), and the migration run completed transactionally rather than dying mid-statement.
• A database restore from a pre-upgrade snapshot is required when any migration is irreversible, when the failure interrupted a migration mid-execution, or when you cannot verify exactly which version the schema is at. In production, a snapshot restore is the lower-risk default precisely because it sidesteps all of these unknowns.

Before choosing, inspect the version table to confirm what actually ran:

php bin/console doctrine:migrations:status
# or query directly:
SELECT version, executed_at FROM doctrine_migration_versions ORDER BY executed_at DESC;

Compare the newest recorded version against the migrations present in the restored codebase. If the table lists versions whose migration classes no longer exist after the lock file restore, doctrine:migrations:rollback may not even be able to locate the down() code it needs — another argument for a snapshot restore.

Order of operations

Order matters because rollback executes PHP code from the migration classes:

1. Restore composer.lock from a known-good copy (version control or backup — do not trust the file left behind by the failed update), then run composer install.
2. Clear the cache: php bin/console cache:clear (or remove var/cache for the target environment).
3. Only then decide on the database. If rolling back, run php bin/console doctrine:migrations:migrate 'prev' or target the specific pre-upgrade version — tested first against a staging copy of the production database.

The subtlety: rollback runs against the restored vendor tree. If the failed upgrade changed Doctrine Migrations itself, the rollback behavior comes from the old version, which is normally what you want — but it means you cannot roll back before restoring dependencies, because the new (possibly broken) code would execute the rollback.

When rollback cannot cleanly undo the damage

Three common cases:

• The migration died mid-transaction on a platform without transactional DDL (notably MySQL/MariaDB), leaving half-applied schema changes with no record in the versions table — rollback will try to undo changes that were never recorded, or skip ones that were.
• down() is empty, throws IrreversibleMigration, or was auto-generated incompletely.
• Data migrations ran inside up(): schema rollback does not restore deleted or transformed rows.

In all three, restore from the pre-upgrade backup and replay nothing. This is why the standard production posture is: take a database snapshot immediately before composer update, and treat migration rollback as a convenience for development, not a production recovery mechanism.

Caveats

This assumes Symfony 6/7 with Doctrine Migrations 3.x; exact table and command names differ in older versions. Verify the migration bundle version and test the full recovery sequence on staging before relying on it. If the failed upgrade also deployed new application code that already served traffic against the migrated schema, check for writes made in the interim — a snapshot restore discards them.