cqrs-implementation

CQRS Implementation

Comprehensive guide to implementing CQRS (Command Query Responsibility Segregation) patterns.

When to Use This Skill

• Separating read and write concerns
• Scaling reads independently from writes
• Building event-sourced systems
• Optimizing complex query scenarios
• Different read/write data models needed
• High-performance reporting requirements

Core Concepts

1. CQRS Architecture

                    ┌─────────────┐
                    │   Client    │
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │                         │
              ▼                         ▼
       ┌─────────────┐          ┌─────────────┐
       │  Commands   │          │   Queries   │
       │    API      │          │    API      │
       └──────┬──────┘          └──────┬──────┘
              │                         │
              ▼                         ▼
       ┌─────────────┐          ┌─────────────┐
       │  Command    │          │   Query     │
       │  Handlers   │          │  Handlers   │
       └──────┬──────┘          └──────┬──────┘
              │                         │
              ▼                         ▼
       ┌─────────────┐          ┌─────────────┐
       │   Write     │─────────►│    Read     │
       │   Model     │  Events  │   Model     │
       └─────────────┘          └─────────────┘

2. Key Components

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates. Treat those templates as reference examples, and review and adapt them before use.

Best Practices

Do's

• Separate command and query models - Different needs
• Use eventual consistency where the business tolerates lag - Define acceptable propagation delay
• Validate in command handlers - Before state change
• Authenticate and authorize every command - Check caller identity and permissions in the command handler before any state change
• Denormalize read models - Optimize for queries
• Bound query inputs - Cap page size and accept sort fields only from a fixed list
• Version your events - For schema evolution
• Make projectors idempotent and validate events - Track event IDs or sequence numbers to reject duplicates and replays, validate schema and version, and accept events only from the trusted event store
• Hold the checkpoint at a failed event - Retry or stop until the failure is handled

Don'ts

• Don't use the read model for command validation - Load state from the write model
• Don't couple read/write schemas - Independent evolution
• Don't make authorization or invariant decisions from read models - Enforce permissions, balances, and uniqueness against the write model in the command handler, with optimistic concurrency
• Don't over-engineer - Start simple
• Don't ignore consistency SLAs - Define acceptable lag