CQRS (Command Query Responsibility Segregation)

Also Known As

TL;DR

Explanation

CQRS (Greg Young) extends Command Query Separation from the method level to the architectural level — different models, and potentially different data stores, handle reads and writes. The write model enforces business rules and emits domain events; the read model is a denormalised, query-optimised projection updated asynchronously. This decoupling allows reads to scale independently of writes, enables event sourcing, and keeps the write model focused on invariants. CQRS adds significant complexity — only apply it where read/write asymmetry genuinely exists.

Diagram

flowchart LR
    subgraph Write Side
        CMD[Command] --> CH[Command Handler]
        CH --> DOM[Domain Model]
        DOM --> ES[(Event Store)]
    end
    subgraph Read Side
        ES -->|Project| RM[(Read Model)]
        QRY[Query] --> QH[Query Handler]
        QH --> RM
    end
    UI[Client] --> CMD
    UI --> QRY
style ES fill:#6e40c9,color:#fff
style RM fill:#238636,color:#fff
style UI fill:#1f6feb,color:#fff

Common Misconception

Why It Matters

Common Mistakes

• Applying CQRS to simple CRUD screens — the complexity is only justified when read and write models genuinely differ.
• Expecting read models to be immediately consistent — CQRS often pairs with eventual consistency, and UIs need to handle that.
• Sharing the write model's domain objects with the read side — that defeats the purpose of separation.
• Implementing CQRS without event sourcing and wondering why read model rebuilding is painful.

Avoid When

• Simple applications where read and write models are identical — CQRS doubles the surface area with no benefit.
• Small teams that cannot maintain two separate models, sync mechanisms, and consistency guarantees.
• Latency-sensitive operations where eventual consistency between command and query sides is unacceptable.
• Greenfield projects — start simple and introduce CQRS only when read/write scaling demands diverge.

When To Use

• High-read, low-write systems where optimised read models (denormalised, cached projections) dramatically improve performance.
• Complex domains where the write model (aggregates, invariants) and read model (flat views, reports) have fundamentally different shapes.
• Event-sourced systems where read models are built by replaying the event stream.
• Systems requiring different scaling strategies for reads vs writes — e.g. read replicas, CDN-cached views.

Code Examples

// No CQRS — read and write mixed in one model:
class OrderService {
    public function getOrder(int $id): Order { return Order::with('items')->find($id); }
    public function placeOrder(array $data): Order { /* validate, create, dispatch events */ }
    // Reads and writes share the same model — can't optimise independently
}

// COMMAND — write side, returns void
class PlaceOrderCommand {
    public function __construct(public readonly CartId $cartId, public readonly UserId $userId) {}
}
class PlaceOrderHandler {
    public function handle(PlaceOrderCommand $cmd): void {
        $cart  = $this->carts->find($cmd->cartId);
        $order = Order::place($cart, $cmd->userId);
        $this->orders->save($order);
    }
}

// QUERY — read side, returns a DTO, never mutates
class OrderSummaryQuery {
    public function __construct(public readonly UserId $userId) {}
}
class OrderSummaryHandler {
    public function handle(OrderSummaryQuery $q): array {
        return $this->db->query('SELECT id,total FROM orders WHERE user_id=?', [$q->userId]);
    }
}

References

• ↗ https://martinfowler.com/bliki/CQRS.html

Tags

Related Terms