doctrine-relations_skill

Overview

This skill helps evolve Symfony Doctrine models and database schema safely with a focus on data integrity, runtime performance, and disciplined rollouts. It guides decisions on ownership, cardinality, transactional boundaries, and migration strategy. Use it to turn relation design and schema changes into predictable, testable outcomes.

How this skill works

The skill inspects entity mappings and migration plans to surface ownership mismatches, potential N+1 sources, and dangerous migration patterns. It recommends mapping adjustments, migration sequencing, and fetch/query tuning for hot paths. It produces concrete entity changes, migration fragments, validation notes, and rollback considerations.

When to use it

• Designing or reviewing entity relationships (OneToOne, OneToMany, ManyToOne, ManyToMany).
• Planning schema evolution that affects foreign keys, nullability, or cardinality.
• Diagnosing performance issues tied to relations (N+1, over-fetching, inefficient joins).
• Preparing migrations for multi-release rollouts or zero-downtime deployments.
• Validating lifecycle callbacks and cascade behaviors before production release.

Best practices

• Model clear ownership and keep owning/inverse sides coherent to avoid ambiguous cascade behavior.
• Break destructive schema changes into multiple, safe migrations across releases rather than a single risky jump.
• Define transactional boundaries explicitly; avoid cross-boundary writes that can cause locking or integrity lapses.
• Tune fetch strategies for hot paths: prefer explicit JOIN queries or partial selects over global EAGER fetching.
• Add targeted tests that assert lifecycle events, cascade effects, and migration forward/backward behavior.

Example use cases

• Convert a nullable ManyToOne into a required relationship with a safe backfill migration and phased constraint addition.
• Resolve an N+1 issue by introducing a single optimized join query and removing inappropriate EAGER mappings.
• Split a ManyToMany into an explicit join entity to add attributes and control cascade semantics.
• Plan a multi-release migration: add new columns, backfill data, then apply NOT NULL and FK constraints in separate steps.
• Validate cascade remove behavior to ensure deleting a parent does not unexpectedly orphan or delete other entities.