home / skills / makfly / superpowers-symfony / doctrine-migrations

doctrine-migrations skill

safe

This skill helps manage Symfony Doctrine migrations safely, optimizing integrity and performance during schema evolution.

npx playbooks add skill makfly/superpowers-symfony --skill doctrine-migrations

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.1 KB

---
name: symfony:doctrine-migrations
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Evolve Symfony Doctrine models and schema safely with integrity, performance, and rollout discipline. Use for doctrine migrations tasks.
---

# Doctrine Migrations (Symfony)

## Use when
- Designing entity relations or schema evolution.
- Improving Doctrine correctness/performance.

## Default workflow
1. Model ownership/cardinality and transactional boundaries.
2. Apply mapping/schema changes with migration safety.
2. Tune fetch/query behavior for hot paths.
2. Verify lifecycle behavior with targeted tests.

## Guardrails
- Keep owning/inverse sides coherent.
- Avoid destructive migration jumps in one release.
- Eliminate accidental N+1 and over-fetching.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.

## Output contract
- Entity/migration changes.
- Integrity and performance decisions.
- Validation outcomes and rollback notes.

## References
- `reference.md`
- `docs/complexity-tiers.md`

Overview

This skill helps evolve Symfony Doctrine models and database schema with an emphasis on data integrity, performance, and disciplined rollout. It guides mapping changes, migration generation, and verification steps to avoid common pitfalls like N+1 queries or destructive schema jumps. Use it to apply safe, testable schema evolution in production systems.

How this skill works

The skill inspects entity mappings, transactional boundaries, and query hotspots to recommend migration strategies and mapping adjustments. It generates or validates migration plans that preserve data integrity and minimize downtime, and it suggests fetch and indexing changes for performance-sensitive paths. Outputs include proposed entity/migration changes, integrity decisions, validation results, and rollback notes.

When to use it

When designing or changing entity relationships and cardinality
When preparing schema changes for production with minimal risk
When diagnosing and eliminating N+1 queries or over-fetching
When tuning fetch strategies and indexes for hot query paths
When needing clear rollback and validation guidance for migrations

Best practices

Model ownership and inverse sides coherently before migrating
Break destructive changes into phased releases rather than one jump
Run targeted tests and schema validations before and after applying migrations
Tune fetch modes and add indexes only after measuring query behavior
Document transactional boundaries and rollback procedures with each migration

Example use cases

Convert a nullable FK to a required relation with phased data backfill and a two-step migration
Split a large table into two with minimal downtime and explicit integrity checks
Detect and remediate an accidental N+1 by changing fetch strategies and adding selective eager loading
Add or tune indexes on a hot endpoint after analyzing slow queries and explain plans
Validate that lifecycle callbacks and cascade rules behave correctly after a model refactor

FAQ

How do I avoid destructive schema changes in a single release?

Break the change into multiple migrations: add new columns, backfill data, switch reads/writes to the new shape, then drop old columns in a later release.

What should I test before deploying migrations?

Run migration dry-runs, data integrity checks, query performance tests for hot paths, and automated tests that exercise affected lifecycle callbacks.