doctrine-migrations_skill

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