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

doctrine-transactions skill

safe

This skill helps evolve Symfony Doctrine models and schema safely by enforcing transactional boundaries, migrations, and performance tuning.

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

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

# Doctrine Transactions (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, emphasizing data integrity, runtime performance, and controlled rollouts. It guides transactional boundaries, mapping changes, and targeted testing to avoid regressions and runtime surprises. It produces concrete entity and migration changes plus validation and rollback notes.

How this skill works

The skill inspects entity ownership, cardinality, and transactional scopes to recommend mapping and migration changes. It evaluates fetch and query patterns to detect N+1 risks and over-fetching, then suggests tuning (fetch modes, joins, indexes). It outputs migration scripts or diffs, integrity decisions, performance trade-offs, and verification steps including tests and rollback plans.

When to use it

Designing or refactoring entity relations and ownership
Introducing schema evolution or database migrations in production
Addressing performance issues caused by Doctrine fetch/query patterns
Hardening transactional boundaries to prevent partial commits or data races
Preparing staged rollouts for risky mapping changes

Best practices

Model clear owning and inverse sides; keep associations coherent to avoid orphaned state
Break destructive migrations into smaller, reversible steps across releases
Define transaction boundaries around use-case intents, not ORM internals
Tune fetch behavior for hot paths: prefer explicit joins or DTO queries over eager collection loading
Verify lifecycle events and cascades with targeted unit and integration tests before rollout

Example use cases

Convert a ManyToMany association into an explicit join entity with safe migration steps
Split a large entity with many associations to reduce fetch cost on common queries
Add a new nullable column, backfill data with batched migrations, then make it non-nullable in a later release
Detect and eliminate an N+1 caused by lazy-loading collections on a critical endpoint
Introduce optimistic locking or shorter transaction scopes to reduce contention on high-write tables

FAQ

Will this skill create migration SQL automatically?

It generates recommended migration changes and scripts or diffs, but you should review and test SQL before applying to production.

How does it handle large data backfills?

It recommends batched, idempotent backfills with progress checkpoints and rollback points to avoid long locks and to permit staged rollouts.