/doctrine-migrations

name: doctrine-migrations
description: Create and manage Doctrine migrations (bundle 4.x, library 3.9) for schema versioning; handle dependencies, rollbacks, and production deployment
capabilities: [read, search, edit, shell]
tags: [doctrine]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash

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`