doctrine-migrations

Doctrine Migrations (Symfony)

Use when

• A mapping change needs a schema migration (new column, index or table).
• Reviewing a generated make:migration or doctrine:migrations:diff file before it is applied.
• Rolling back a version, or deploying pending migrations to production.
• Tuning doctrine_migrations.yaml (transactional, all_or_nothing, enable_service_migrations).

Default workflow

1. Change the entity mapping, then generate the migration with make:migration or doctrine:migrations:diff.
2. Read every addSql() line: a rename can appear as drop plus add, and index churn is common.
3. Write a real down() that reverses up(), and keep one concern per migration.
4. Check doctrine:migrations:status, preview with doctrine:migrations:migrate --dry-run, then run doctrine:migrations:migrate.
5. Roll back with doctrine:migrations:migrate prev or doctrine:migrations:execute with --down.
6. With several entity managers, pass --em to every migrations command.

Guardrails

• Never edit an already-applied migration: add a new one.
• Keep diff-generated migrations schema only; put data changes in a dedicated, idempotent migration or command.
• Keep the typed signatures up(Schema $schema): void and down(Schema $schema): void.
• all_or_nothing is mostly effective on PostgreSQL, since most MySQL DDL commits implicitly.

Progressive disclosure

• Use this file for execution posture and risk controls.
• Open references when deep implementation details are needed.

Output contract

• Migration files with a reviewed up() and a working down().
• Output of doctrine:migrations:status and the dry-run, plus the rollback command.
• Any doctrine_migrations.yaml change and why.

References

• reference.md