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, KurrentDB 26.2.3, ex-EventStoreDB), saga patterns, outbox, exemples concrets, migration progressive d'un CRUD vers CQRS, checklists par phase : voir @.claude/skills/cqrs/REFERENCE.md.
1---2name: cqrs-33description: "CQRS - Command Query Responsibility Segregation. Use when implementing DDD patterns, separating read/write models, event sourcing, or building scalable architectures with heterogeneous performance requirements."4context: fork5files: ["**/Command*.php", "**/Query*.php", "**/Handler*.php", "**/Projector*.php", "**/ReadModel*.php", "**/WriteModel*.php"]6metadata:7 source: https://skillmd.com/skills/thebeardedbearsas/cqrs-38---910# CQRS — Quick Reference1112CQRS (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é.1314## Quand utiliser1516| Pertinent | Pas pertinent |17|-----------|---------------|18| Domaine métier complexe avec règles d'invariants riches | CRUD simple, domaine pauvre |19| Ratio lectures/écritures > 10× | Petits projets, équipe junior |20| Audit / compliance (Event Sourcing naturel) | Cohérence immédiate requise |21| Read models hétérogènes (mobile vs analytics vs back-office) | Modèle de données stable et unique |22| Scale différencié reads vs writes (replicas, cache, search) | Charge faible, monolithe modeste |2324**Règle d'or :** commencer par une architecture classique. Migrer vers CQRS lorsqu'**au moins 2** des cas pertinents sont présents simultanément.2526## Architecture en 30 secondes2728```29[ User ]30 ↓31[ Command ]──────────▶ [ Write Model (Domain) ]32 ↓ persist + emit33 [ Event(s) ]34 ↓35[ Query ] ◀───── [ Read Model (denormalised) ] ◀── projections36```3738- **Command side** : modèle normalisé, focus invariants métier. Écrit, ne lit que ce qui est nécessaire à la validation.39- **Query side** : modèle dénormalisé, focus performance lecture. N'a pas de logique métier.40- **Projections** : transforment les events en read models. **Eventually consistent**.4142## Trade-off central4344| Bénéfice | Coût |45|----------|------|46| Scale indépendant lecture / écriture | Eventual consistency (≈ 50-500 ms latency typique) |47| Read models taillés pour chaque besoin | Plus de code à maintenir (2 modèles) |48| Event Sourcing devient facile à brancher | Debugging plus complexe (event flow) |49| Audit trail naturel | Migration tardive très coûteuse |5051## Patterns associés (souvent ensemble)5253- **Event Sourcing** : stocker la séquence d'events comme source de vérité, le write model est reconstruit en replay.54- **Saga / Process Manager** : orchestrer des transactions distribuées via events.55- **Outbox Pattern** : garantir l'atomicité publication event + write DB.56- **Materialized Views** : projections persistées en table dédiée pour query speed.5758## Anti-patterns critiques5960- ❌ CQRS sans cas d'usage clair → over-engineering, double charge cognitive.61- ❌ Read model qui exécute des règles métier → bug d'invariants à chaque projection.62- ❌ Projections synchrones → on perd le bénéfice scalability.63- ❌ Event Sourcing sans snapshots → replay de millions d'events au boot.64- ❌ Command qui retourne data complète → c'est une Query déguisée.6566## Pour aller plus loin6768> Implémentations Symfony / Laravel / .NET, Event Sourcing (Prooph, KurrentDB 26.2.3, ex-EventStoreDB), saga patterns, outbox, exemples concrets, migration progressive d'un CRUD vers CQRS, checklists par phase : voir `@.claude/skills/cqrs/REFERENCE.md`.