cqrs

CQRS (Command Query Responsibility Segregation)

CQRS is a pattern that separates read and update operations for a data store. Instead of using a single model for both, you have a Command Model (Write) and a Query Model (Read).

When to Use

• Asymmetric Read/Write Workloads: Systems where reads outnumber writes by 100:1 or 1000:1 and require independent horizontal scaling.
• Complex Reporting & Search Views: Aggregating data across multiple aggregates into denormalized read stores (Elasticsearch, Read Replicas).
• Collaboration & High Concurrency: Optimizing write performance and transactional consistency while delivering instant query responses.
• Pairing with Event Sourcing: When state changes are captured as events and read models are asynchronously projected from event streams.

Quick Start

// Command Side (Write) - Optimized for Integrity
class CreateOrderCommand { ... }
class OrderAggregate {
    create(cmd: CreateOrderCommand) {
        // Validate business rules
        // Save to DB (Normalized / Event Store)
    }
}

// Query Side (Read) - Optimized for Speed
class GetOrderSummaryQuery { ... }
class OrderSummaryProjector {
    // Listens to "OrderCreated" event
    on(event) {
        // Update a flat "Read DB" (e.g., ElasticSearch, Redis, Document DB)
        // optimized for the specific UI view
    }
}

Core Concepts

Separation of Command and Query Models

Commands represent intent to mutate state (void return or ID); Queries request data without side effects:

Client
  ├── Command: POST /orders (CreateOrderCommand) ──→ Command Handler ──→ Write DB (Postgres)
  │                                                                           │ (CDC / Events)
  └── Query:   GET /orders/summary (OrderSummary) ←── Read Handler   ←── Read DB (Elastic/Redis)

Command Handlers with Explicit Domain Mutex

Validates permissions and business invariants before committing writes:

// commands/cancel-order.command.ts
export interface CancelOrderCommand {
  orderId: string;
  reason: string;
  requestedByUserId: string;
}

export class CancelOrderCommandHandler {
  constructor(private readonly orderRepo: OrderRepositoryPort) {}

  async handle(cmd: CancelOrderCommand): Promise<void> {
    const order = await this.orderRepo.getById(cmd.orderId);
    if (!order) throw new Error("Order not found");
    order.cancel(cmd.reason, cmd.requestedByUserId);
    await this.orderRepo.save(order);
  }
}