| name | cqrs |
| description | CQRS - Command Query Responsibility Segregation. Use when implementing DDD patterns, separating read/write models, event sourcing, or building scalable architectures with heterogeneous performance requirements. |
| context | fork |
| triggers | {"files":["**/Command*.php","**/Query*.php","**/Handler*.php","**/Projector*.php","**/ReadModel*.php","**/WriteModel*.php"],"keywords":["cqrs","command","query","event sourcing","projection","read model","write model","command handler","query handler"]} |
| auto_suggest | true |
| disable-model-invocation | true |
CQRS — Quick Reference
CQRS (Command Query Responsibility Segregation) sépare les opérations d'écriture et de lecture dans des modèles distincts. N'est pas par défaut — c'est une optimisation à activer quand le coût de la complexité est justifié.
Quand utiliser
| Pertinent | Pas pertinent |
|---|
| Domaine métier complexe avec règles d'invariants riches | CRUD simple, domaine pauvre |
| Ratio lectures/écritures > 10× | Petits projets, équipe junior |
| Audit / compliance (Event Sourcing naturel) | Cohérence immédiate requise |
| Read models hétérogènes (mobile vs analytics vs back-office) | Modèle de données stable et unique |
| Scale différencié reads vs writes (replicas, cache, search) | Charge faible, monolithe modeste |
Règle d'or : commencer par une architecture classique. Migrer vers CQRS lorsqu'au moins 2 des cas pertinents sont présents simultanément.
Architecture en 30 secondes
[ User ]
↓
[ Command ]──────────▶ [ Write Model (Domain) ]
↓ persist + emit
[ Event(s) ]
↓
[ Query ] ◀───── [ Read Model (denormalised) ] ◀── projections
- Command side : modèle normalisé, focus invariants métier. Écrit, ne lit que ce qui est nécessaire à la validation.
- Query side : modèle dénormalisé, focus performance lecture. N'a pas de logique métier.
- Projections : transforment les events en read models. Eventually consistent.
Trade-off central
| Bénéfice | Coût |
|---|
| Scale indépendant lecture / écriture | Eventual consistency (≈ 50-500 ms latency typique) |
| Read models taillés pour chaque besoin | Plus de code à maintenir (2 modèles) |
| Event Sourcing devient facile à brancher | Debugging plus complexe (event flow) |
| Audit trail naturel | Migration tardive très coûteuse |
Patterns associés (souvent ensemble)
- Event Sourcing : stocker la séquence d'events comme source de vérité, le write model est reconstruit en replay.
- Saga / Process Manager : orchestrer des transactions distribuées via events.
- Outbox Pattern : garantir l'atomicité publication event + write DB.
- Materialized Views : projections persistées en table dédiée pour query speed.
Anti-patterns critiques
- ❌ CQRS sans cas d'usage clair → over-engineering, double charge cognitive.
- ❌ Read model qui exécute des règles métier → bug d'invariants à chaque projection.
- ❌ Projections synchrones → on perd le bénéfice scalability.
- ❌ Event Sourcing sans snapshots → replay de millions d'events au boot.
- ❌ Command qui retourne data complète → c'est une Query déguisée.
Pour aller plus loin
Implémentations Symfony / Laravel / .NET, Event Sourcing (Prooph, EventStoreDB), saga patterns, outbox, exemples concrets, migration progressive d'un CRUD vers CQRS, checklists par phase : voir @.claude/skills/cqrs/REFERENCE.md.
