Skip to main content
skill CX Codex

doctrine-fetch-modes — Claude Code skill: what it does, how to install

doctrine-fetch-modes guides Doctrine ORM and DBAL 4 query optimization in Symfony. Fixes N+1 queries, configures lazy loading, and implements DTO hydration.

MIT ★ 234 updated 2026-10-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dev-toolings/superpowers-symfony --skill doctrine-fetch-modes -a claude-code
Open on GitHub

What doctrine-fetch-modes does

The skill guides Claude Code in refining database queries across Symfony applications. It targets N+1 queries with repository fetch joins using addSelect() and leftJoin(), configures EXTRA_LAZY mappings for large collections, and applies Query::HINT_READ_ONLY when entities are only read or indexed by key.

Because PARTIAL syntax in DQL fails on ORM 3.0 through 3.2, the skill shifts read-only lists to readonly DTOs via SELECT NEW. These DTOs are unmanaged, meaning they cannot be flushed back to the database. For raw SQL, it swaps removed DBAL helpers like fetchAll() for DBAL 4 methods such as fetchAllAssociative() and fetchOne().

What it helps with

  • eliminate N+1 query loops using repository fetch joins
  • project read-only data into DTOs with SELECT NEW
  • configure EXTRA_LAZY fetching for entity collections
  • update raw SQL queries to DBAL 4 fetch methods

Example prompts for the agent

  • Fix the N+1 query issue in the order repository using a fetch join
  • Project this customer query into a readonly DTO with SELECT NEW
  • Refactor repository raw SQL calls to DBAL 4 fetchAllAssociative

How to install doctrine-fetch-modes

1Skills CLI (Vercel)

npx skills add dev-toolings/superpowers-symfony --skill doctrine-fetch-modes -a claude-code

2Manually: put the files in place

~/.claude/skills/doctrine-fetch-modes/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doctrine-fetch-modes/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about doctrine-fetch-modes

How to install doctrine-fetch-modes in Claude Code?

Run npx skills add dev-toolings/superpowers-symfony --skill doctrine-fetch-modes -a claude-code.

What does doctrine-fetch-modes do?

It sets guidelines for resolving N+1 issues in Doctrine, mapping fetch joins, applying DTO hydration, and targeting DBAL 4 APIs.

Why does the skill avoid PARTIAL objects in DQL?

DQL PARTIAL syntax fails in Doctrine ORM 3.0 through 3.2, making SELECT NEW DTO projections the reliable replacement.

Source text

SKILL.md · MIT
---
name: doctrine-fetch-modes
description: Optimize Doctrine fetching with DTO hydration (SELECT NEW), fetch joins, lazy loading, query hints, and DBAL 4 access
capabilities: [read, search, edit, shell]
tags: [doctrine, performance]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash
---

# Doctrine Fetch Modes (Symfony)

## Use when
- A list or detail endpoint runs one query per row (N+1) on a relation.
- A read-only list needs a few columns, not full managed entities.
- Choosing `LAZY`, `EAGER` or `EXTRA_LAZY` on a mapping, or porting ORM 2 code that relied on `PARTIAL` objects.
- A report or projection query drops to raw SQL through DBAL 4.

## Default workflow
1. Confirm the N+1 or over-fetch in the Symfony profiler before changing any mapping.
2. Keep relations on `fetch: 'LAZY'`; set `fetch: 'EXTRA_LAZY'` on large collections so `count()`, `contains()` and `slice()` run targeted SQL.
3. Load the relations a use case needs with a fetch join in the repository (`addSelect()` plus `leftJoin()`).
4. For read-only lists, project into a `readonly` DTO with `SELECT NEW` (constructor argument order must match the `NEW` list).
5. Use `Query::HINT_READ_ONLY` or an index-by alias (`createQueryBuilder('p', 'p.id')`) when the result is only displayed or looked up by id.
6. For raw SQL, use the DBAL 4 methods (`fetchAllAssociative()`, `fetchOne()`, `executeStatement()`).

## Guardrails
- `PARTIAL` in DQL fails on ORM 3.0 to 3.2 and only returns from 3.3: use `SELECT NEW` DTOs for read-only lists instead.
- Avoid `fetch: 'EAGER'` on a mapping; a fetch join in the query gives the same result per use case.
- `SELECT NEW` returns DTOs, not managed entities: never modify or flush them.
- DBAL 4 removed `query()`, `exec()` and `fetchAll()`.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.

## Output contract
- Repository methods with the fetch strategy chosen per use case.
- DTO classes and the `SELECT NEW` queries that fill them.
- Query count before and after, from the profiler or `doctrine:query:dql --show-sql`.

## References
- `reference.md`

© dev-toolings · MIT · dev-toolings/superpowers-symfony

Similar skills

All skills for Backend and APIs →

From the same set51

The whole set →
symfony-messenger A skill for async message handling with Symfony Messenger: configures transports, handlers, and retry strategies. CX Codex +1 ★ 234repo stars api-platform-security api-platform-security secures API Platform operations with security expressions, voters, and validation-phase access checks in Symfony. CX Codex +1 ★ 234repo stars e2e-panther-playwright The e2e-panther-playwright skill guides Symfony E2E tests with Panther for browser flows and Playwright for more involved cases. Use it when JavaScript behavior is beyond what WebTestCase can observe. CX Codex +1 ★ 234repo stars doctrine-relations Skill guides you through defining Doctrine relationships (OneToMany, ManyToMany, ManyToOne) with correct owning and inverse sides, cascade strategies, and N+1 query prevention. CX Codex +1 ★ 234repo stars api-platform-resources api-platform-resources is a Claude Code skill for configuring API Platform resources for REST and GraphQL. It activates for resource creation and changes to operations, pagination, or OpenAPI docs. CX Codex +1 ★ 234repo stars messenger-retry-failures messenger-retry-failures sorts out failed Symfony Messenger handlers: whether a message deserves another attempt, when it goes straight to the failure transport, and how to pull it back. CX Codex +1 ★ 234repo stars api-platform-state-providers Configures API Platform State Providers and Processors in Symfony. It helps decouple data retrieval and persistence from Doctrine entities. CX Codex +1 ★ 234repo stars api-platform-dto-resources The api-platform-dto-resources skill decouples your API contract from Doctrine entities in API Platform via Symfony's Object Mapper. CX Codex +1 ★ 234repo stars

Project sponsors

Companies that keep this analytics open