playbooks

home / skills / makfly / superpowers-symfony / doctrine-fetch-modes

doctrine-fetch-modes skill

/skills/doctrine-fetch-modes

This skill helps you safely evolve Symfony Doctrine models and schema, improving integrity, performance, and rollout discipline through targeted fetch mode

npx playbooks add skill makfly/superpowers-symfony --skill doctrine-fetch-modes

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-fetch-modes
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 fetch modes tasks.
---

# Doctrine Fetch Modes (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 focus on fetch modes, integrity, and rollout discipline. It guides safe mapping changes, migration planning, and fetch behavior tuning to avoid N+1 and over-fetching. Use it to balance correctness, performance, and predictable deployments.

How this skill works

The skill inspects entity relationships, current fetch strategies, and migration risks to produce concrete change suggestions. It recommends ownership and cardinality adjustments, safe migration steps, and targeted query/fetch tuning for hot paths. It outputs entity and migration edits, validation results, and rollback notes for each proposed change.

When to use it

  • Designing or refactoring entity relationships and ownership semantics
  • Preparing schema evolution that affects relations or cardinality
  • Identifying and eliminating N+1 queries and excessive eager fetching
  • Tuning fetch/query behavior for high-throughput or latency-sensitive endpoints
  • Validating lifecycle callbacks and transactional boundaries before release

Best practices

  • Keep owning and inverse sides coherent and canonical to avoid ORM surprises
  • Break destructive migrations into staged releases with backward-compatible steps
  • Prefer lazy loading by default; selectively eager-load known hot-path relations
  • Use targeted DQL or repository methods for complex joins instead of global fetch overrides
  • Add focused integration tests that assert fetch behavior and lifecycle effects before rollout

Example use cases

  • Convert a ManyToMany mapping into an explicit join entity to add metadata without breaking reads
  • Stage a nullable->non-nullable foreign key migration with a backfill and feature-flagged consumer switch
  • Identify N+1 hotspots on list endpoints and introduce JOIN FETCH or optimized repository queries
  • Change fetch mode to EXTRA_LAZY for large collections to avoid loading full collections into memory
  • Validate that cascade and orphanRemoval semantics remain correct after relationship ownership changes

FAQ

How do I avoid a destructive migration that impacts live traffic?

Split the change: add nullable columns or new tables, backfill data, switch application code to read the new shape, then make columns non-nullable in a subsequent release.

When should I prefer EXTRA_LAZY over LAZY?

Use EXTRA_LAZY for very large collections where operations like count/contains should not initialize the whole collection; use LAZY for typical collections where proxies are sufficient.