playbooks

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

doctrine-relations skill

/skills/doctrine-relations

This skill helps you evolve Symfony Doctrine models and migrations safely, optimizing relations, integrity, and rollout discipline across entities.

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

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-relations
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 relations tasks.
---

# Doctrine Relations (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 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.

FAQ

How do you avoid accidental N+1 queries when evolving relations?

Prefer explicit repository queries with JOINs for hot paths, avoid global EAGER mappings, and add integration tests that assert query counts during critical flows.

What’s the safest way to add a NOT NULL foreign key to a large table?

Do it in phases: add the new FK column nullable, backfill values in batches, deploy code that reads/writes both columns if needed, then add the NOT NULL constraint and enforce the FK in a subsequent release.