System Design (HLD)Distributed Data Patterns

CQRS Pattern

LevelAdvanced

Duration75 mins

TopicDistributed Data Patterns

1 / 5

Command Query Responsibility Segregation - Introduction

The Fundamental Tension in Data Access

Every software system that persists data faces a fundamental tension: the operations that modify data and the operations that read data have fundamentally different characteristics, requirements, and optimization strategies. Yet traditional architectures force these vastly different concerns through the same models, the same services, and often the same database tables.

Consider an e-commerce platform. When a customer places an order, the system must:

Validate inventory availability
Process payment
Create order records
Update stock levels
Trigger fulfillment workflows

This is a complex, transactional operation requiring strict consistency guarantees. But when the same customer views their order history, the system needs:

Fast response times
The ability to aggregate data from multiple sources
Denormalized views optimized for display
The capacity to serve thousands of concurrent requests

These are fundamentally different problems. Forcing them through the same architecture creates inevitable compromises.

What You Will Learn

By the end of this page, you will understand the core principle of CQRS, its historical origins, why the traditional CRUD model creates artificial constraints, and how separating commands from queries enables entirely new architectural possibilities. This foundational understanding is essential before exploring implementation patterns.

Origins and Evolution of CQRS

CQRS didn't emerge in a vacuum—it evolved from decades of software architecture experience. Understanding its lineage helps explain why it exists and where it provides value.

Command Query Separation (CQS): The Intellectual Foundation

Bertrand Meyer, creator of the Eiffel programming language, introduced Command Query Separation (CQS) in the 1980s as a design principle for object-oriented programming:

"Every method should either be a command that performs an action, or a query that returns data to the caller, but not both."

In CQS:

Commands (also called modifiers) change state but return nothing
Queries return data but do not modify state

This principle promotes predictability and reduces side effects. When you call a query method, you know the system state won't change. When you call a command, you know you're triggering a mutation.

cqs-example.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// CQS-COMPLIANT DESIGN
 
class ShoppingCart {
    private items: CartItem[] = [];
 
    // COMMAND: Modifies state, returns nothing
    addItem(product: Product, quantity: number): void {
        const existingItem = this.items.find(i => i.productId === product.id);
        if (existingItem) {
            existingItem.quantity += quantity;
        } else {
            this.items.push({ productId: product.id, quantity, price: product.price });
        }
    }
 
    // COMMAND: Modifies state, returns nothing
    removeItem(productId: string): void {
        this.items = this.items.filter(i => i.productId !== productId);
    }
 
    // QUERY: Returns data, does not modify state
    getTotal(): number {
        return this.items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
    }
 
    // QUERY: Returns data, does not modify state
    getItemCount(): number {
        return this.items.reduce((sum, item) => sum + item.quantity, 0);
    }
 
    // QUERY: Returns data, does not modify state
    getItems(): ReadonlyArray<CartItem> {
        return [...this.items]; // Return copy to prevent mutation
    }
}
 
// CQS VIOLATION (Anti-pattern)
class BadShoppingCart {
    // VIOLATES CQS: Modifies state AND returns data
    addItemAndGetTotal(product: Product, quantity: number): number {
        this.items.push({ productId: product.id, quantity, price: product.price });
        return this.getTotal(); // Mix of command and query
    }
}

From CQS to CQRS: Architectural Evolution

Greg Young, in the mid-2000s, extrapolated Meyer's method-level principle to the architectural level, creating Command Query Responsibility Segregation (CQRS):

"CQS applies to individual methods. CQRS applies to entire system architectures—using different models for commands (writes) and queries (reads)."

This is a crucial distinction. While CQS tells you how to design methods, CQRS tells you how to design systems. The implications are profound:

Aspect	CQS (Method Level)	CQRS (System Level)
Scope	Single object's methods	Entire bounded context
Models	Same object for read/write	Separate read and write models
Storage	Single database table	Potentially separate databases
Optimization	None	Independent optimization of each path
Consistency	Immediate	Can be eventual between models

The Mental Leap

The key insight of CQRS is recognizing that reads and writes can be entirely separate models maintained by different services, stored in different databases, and optimized independently. Most developers initially struggle with this because it challenges the implicit assumption that there's one 'true' model of data.

The Problem with Traditional CRUD

To understand why CQRS exists, we must examine the limitations it addresses. Traditional architectures follow the CRUD pattern: Create, Read, Update, Delete—treating all data operations as variations of the same fundamental operation.

The CRUD Mental Model:

┌─────────────────────────────────────────────────────┐
│                   APPLICATION                        │
│  ┌─────────────────────────────────────────────┐    │
│  │            Unified Domain Model              │    │
│  │  (One model handles reads AND writes)        │    │
│  └─────────────────────────────────────────────┘    │
│                        │                             │
│                        ▼                             │
│  ┌─────────────────────────────────────────────┐    │
│  │              Data Access Layer               │    │
│  │  (Same repository for all operations)        │    │
│  └─────────────────────────────────────────────┘    │
│                        │                             │
│                        ▼                             │
│  ┌─────────────────────────────────────────────┐    │
│  │           Single Database Schema             │    │
│  │  (Normalized for writes, queries span joins) │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

This approach works beautifully for simple applications. But as systems grow, inherent tensions emerge:

Inherent Tensions in CRUD Architecture

•Normalization vs. Query Performance — Data is normalized for write efficiency (no redundancy), but reads require expensive JOINs across multiple tables. A product listing page might JOIN products, inventory, pricing, reviews, and seller information.
•Write Validation vs. Read Simplicity — Domain models often contain validation logic, invariant enforcement, and business rules essential for writes—but entirely unnecessary overhead when simply displaying data.
•Transactional Consistency vs. Read Scalability — Write operations require ACID transactions and strong consistency. But read-heavy workloads often benefit from eventual consistency and replicated read models.
•Schema Rigidity vs. View Flexibility — The database schema is optimized for one purpose. But different views need different data shapes—a mobile app might need condensed data while dashboards need aggregations.
•Aggregate Boundaries vs. Query Scope — Domain-Driven Design encourages well-defined aggregate boundaries for writes. But queries frequently need to span multiple aggregates, creating awkward cross-aggregate coordination.

crud-compromise.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
// TRADITIONAL CRUD: ONE MODEL FOR EVERYTHING
 
interface Order {
    id: string;
    customerId: string;
    items: OrderItem[];
    status: OrderStatus;
    shippingAddress: Address;
    billingAddress: Address;
    paymentInfo: PaymentInfo;
    createdAt: Date;
    updatedAt: Date;
    
    // Validation for writes
    validate(): ValidationResult;
    
    // Business logic for state transitions
    canCancel(): boolean;
    cancel(): void;
    
    // Used for display but clutters the write model
    getDisplayTotal(): string;
    getStatusLabel(): string;
}
 
class OrderService {
    // WRITE: Complex validation and business rules
    async createOrder(request: CreateOrderRequest): Promise<Order> {
        const order = new Order(request);
        order.validate(); // Complex validation
        
        // Transaction across multiple aggregates
        await this.beginTransaction();
        await this.inventoryService.reserve(order.items);
        await this.paymentService.authorize(order.paymentInfo);
        await this.orderRepository.save(order);
        await this.commitTransaction();
        
        return order;
    }
    
    // READ: Just needs to display data
    async getOrderHistory(customerId: string): Promise<Order[]> {
        // But we fetch the ENTIRE Order model
        // Including validation logic we won't use
        // Including payment info we don't need to display
        // Requiring JOINs across Order, OrderItem, Address, Payment
        return this.orderRepository.findByCustomerId(customerId);
    }
    
    // THE PROBLEM: getOrderHistory doesn't need:
    // - Validation methods
    // - Full payment details
    // - State transition logic
    // - Shipping calculations
    // 
    // It ONLY needs:
    // - Order ID, date, status
    // - Item summaries
    // - Total amount
    // 
    // But CRUD forces us to use the same model.
}

The Scaling Problem:

In most applications, reads vastly outnumber writes. On a typical e-commerce platform:

Operation Type	Frequency	Characteristics
Page Views (reads)	10,000/second	Simple, cacheable
Searches (reads)	1,000/second	Complex aggregations
Add to Cart (writes)	100/second	Low validation
Place Order (writes)	10/second	High validation, transactional
Update Profile (writes)	1/second	Simple

The read-to-write ratio is often 100:1 or higher. Yet CRUD forces both through the same pipeline, meaning:

Reads are slowed by infrastructure optimized for write consistency
Writes can't be optimized without compromising read performance
Scaling means duplicating everything—even the write-oriented logic you don't need for reads

The One-Model Fallacy

The fundamental error in CRUD thinking is assuming that a single representation of data serves all purposes well. This is like insisting a carpenter use the same tool for sawing, hammering, and measuring. Different operations have different optimal representations.

The CQRS Core Principle

CQRS addresses these tensions through one radical insight: use separate models for reading and writing data. Not just separate classes—potentially separate services, separate databases, and separately optimized infrastructure.

The CQRS Mental Model:

┌────────────────────────────────────────────────────────────────┐
│                       APPLICATION                               │
│                                                                  │
│   ╔══════════════════════╗      ╔══════════════════════╗        │
│   ║    COMMAND SIDE      ║      ║     QUERY SIDE       ║        │
│   ║                      ║      ║                      ║        │
│   ║  ┌────────────────┐  ║      ║  ┌────────────────┐  ║        │
│   ║  │ Command Model  │  ║      ║  │  Query Model   │  ║        │
│   ║  │ (Rich Domain)  │  ║      ║  │  (Read DTOs)   │  ║        │
│   ║  └───────┬────────┘  ║      ║  └───────▲────────┘  ║        │
│   ║          │           ║      ║          │           ║        │
│   ║  ┌───────▼────────┐  ║      ║  ┌───────┴────────┐  ║        │
│   ║  │ Write Database │  ║─────▶║  │ Read Database  │  ║        │
│   ║  │ (Normalized)   │  ║ sync ║  │ (Denormalized) │  ║        │
│   ║  └────────────────┘  ║      ║  └────────────────┘  ║        │
│   ╚══════════════════════╝      ╚══════════════════════╝        │
│                                                                  │
└────────────────────────────────────────────────────────────────┘

Core CQRS Principles

•Separate Models — Commands use a rich domain model focused on business rules and invariant protection. Queries use lean DTOs optimized purely for display.
•Separate Paths — Commands and queries follow completely different code paths. They may share no infrastructure beyond the synchronization mechanism.
•Independent Optimization — The command side can use a normalized relational database. The query side can use denormalized read replicas, search indices, or materialized views.
•Independent Scaling — Read and write infrastructure scale independently. A 100:1 read-to-write ratio means 100x more query capacity—without scaling write infrastructure.
•Eventual Consistency (Optional) — The read model may lag behind the write model. This enables asynchronous synchronization and better fault isolation.

cqrs-architecture.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
// ========================================
// COMMAND SIDE: RICH DOMAIN MODEL
// ========================================
 
// Domain aggregate with full business logic
class Order {
    private id: OrderId;
    private items: OrderItem[];
    private status: OrderStatus;
    private events: DomainEvent[] = [];
 
    constructor(customerId: CustomerId, items: OrderItemRequest[]) {
        this.validate(items);
        this.id = OrderId.generate();
        this.items = items.map(i => OrderItem.create(i));
        this.status = OrderStatus.PENDING;
        this.events.push(new OrderCreatedEvent(this.id, customerId, items));
    }
 
    private validate(items: OrderItemRequest[]): void {
        if (items.length === 0) throw new EmptyOrderError();
        if (items.some(i => i.quantity <= 0)) throw new InvalidQuantityError();
        // Complex validation logic...
    }
 
    ship(trackingNumber: string): void {
        if (this.status !== OrderStatus.CONFIRMED) {
            throw new InvalidStateTransitionError('Cannot ship unconfirmed order');
        }
        this.status = OrderStatus.SHIPPED;
        this.events.push(new OrderShippedEvent(this.id, trackingNumber));
    }
 
    cancel(reason: string): void {
        if (!this.canCancel()) {
            throw new InvalidStateTransitionError('Order cannot be cancelled');
        }
        this.status = OrderStatus.CANCELLED;
        this.events.push(new OrderCancelledEvent(this.id, reason));
    }
 
    private canCancel(): boolean {
        return [OrderStatus.PENDING, OrderStatus.CONFIRMED].includes(this.status);
    }
 
    getDomainEvents(): DomainEvent[] {
        return [...this.events];
    }
}
 
// Command handler
class CreateOrderHandler {
    constructor(
        private orderRepository: OrderRepository,
        private eventBus: EventBus
    ) {}
 
    async handle(command: CreateOrderCommand): Promise<OrderId> {
        // Create domain aggregate (validation happens here)
        const order = new Order(command.customerId, command.items);
        
        // Persist to write database
        await this.orderRepository.save(order);
        
        // Publish events for read model synchronization
        await this.eventBus.publish(order.getDomainEvents());
        
        return order.id;
    }
}
 
// ========================================
// QUERY SIDE: LEAN READ MODELS
// ========================================
 
// Read model: Just data, no behavior
interface OrderSummaryDto {
    orderId: string;
    customerName: string;
    itemCount: number;
    totalAmount: number;
    status: string;
    createdAt: string;
}
 
interface OrderDetailDto {
    orderId: string;
    customerName: string;
    items: Array<{
        productName: string;
        quantity: number;
        unitPrice: number;
        lineTotal: number;
    }>;
    subtotal: number;
    tax: number;
    shipping: number;
    total: number;
    status: string;
    timeline: Array<{
        status: string;
        timestamp: string;
    }>;
}
 
// Query handler: Direct database queries, no domain logic
class OrderQueryHandler {
    constructor(private readDatabase: ReadDatabase) {}
 
    async getOrderHistory(customerId: string): Promise<OrderSummaryDto[]> {
        // Direct query against denormalized read model
        // No JOINs needed—data already in optimal shape
        return this.readDatabase.query(`
            SELECT order_id, customer_name, item_count, 
                   total_amount, status, created_at
            FROM order_summaries
            WHERE customer_id = $1
            ORDER BY created_at DESC
        `, [customerId]);
    }
 
    async getOrderDetail(orderId: string): Promise<OrderDetailDto> {
        // Pre-computed and stored in optimal format
        return this.readDatabase.queryOne(`
            SELECT * FROM order_details WHERE order_id = $1
        `, [orderId]);
    }
}
 
// ========================================
// SYNCHRONIZATION: CONNECTING THE MODELS
// ========================================
 
class OrderReadModelProjection {
    constructor(private readDatabase: ReadDatabase) {}
 
    async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
        // Project domain event into read model
        await this.readDatabase.upsert('order_summaries', {
            order_id: event.orderId,
            customer_id: event.customerId,
            customer_name: await this.lookupCustomerName(event.customerId),
            item_count: event.items.length,
            total_amount: this.calculateTotal(event.items),
            status: 'Pending',
            created_at: event.timestamp,
        });
 
        await this.readDatabase.upsert('order_details', {
            order_id: event.orderId,
            // ... full detail projection
        });
    }
 
    async handleOrderShipped(event: OrderShippedEvent): Promise<void> {
        await this.readDatabase.update('order_summaries', 
            { order_id: event.orderId },
            { status: 'Shipped' }
        );
        
        await this.readDatabase.appendToTimeline('order_details',
            event.orderId,
            { status: 'Shipped', timestamp: event.timestamp }
        );
    }
}

The Conceptual Leap

Notice how the command side and query side have almost nothing in common. The Order aggregate contains business logic and validation. The OrderSummaryDto contains only display data. They're not the same entity in different formats—they're conceptually different things that happen to relate to the same real-world concept.

Types of CQRS Implementation

CQRS exists on a spectrum. Not all implementations require separate databases or complex event systems. Understanding the options helps you choose the right level of separation for your needs.

Level 1: Same Database, Different Models

The simplest form of CQRS uses the same database but different code paths. Commands use rich domain objects; queries use lightweight query services that return DTOs directly.

level-1-cqrs.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// LEVEL 1: SAME DATABASE, DIFFERENT MODELS
 
// Command side: Uses ORM with full domain model
class OrderCommandService {
    async createOrder(command: CreateOrderCommand): Promise<string> {
        const order = new Order(command);
        await this.orderRepository.save(order); // ORM persistence
        return order.id;
    }
}
 
// Query side: Direct SQL, bypassing ORM entirely
class OrderQueryService {
    async getOrderSummaries(customerId: string): Promise<OrderSummaryDto[]> {
        // Direct database query—no ORM, no domain objects
        return this.database.query(`
            SELECT 
                o.id as order_id,
                o.created_at,
                o.status,
                COUNT(oi.id) as item_count,
                SUM(oi.quantity * oi.unit_price) as total
            FROM orders o
            LEFT JOIN order_items oi ON oi.order_id = o.id
            WHERE o.customer_id = $1
            GROUP BY o.id
            ORDER BY o.created_at DESC
        `, [customerId]);
    }
}
 
// PROs:
// - Simple to implement
// - Single source of truth
// - Strong consistency
// - No synchronization needed
 
// CONs:
// - Query performance limited by normalized schema
// - Same database handles both loads
// - Read and write scaling tied together

Level 2: Separate Read Database

The query side reads from a separate database optimized for reads. Changes from the write database are synchronized (often asynchronously) to the read database.

level-2-cqrs.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
// LEVEL 2: SEPARATE READ DATABASE
 
// Write side: Relational database with normalized schema
class OrderCommandService {
    constructor(
        private writeDb: PostgresDatabase,
        private eventPublisher: EventPublisher
    ) {}
 
    async createOrder(command: CreateOrderCommand): Promise<string> {
        const order = new Order(command);
        
        await this.writeDb.transaction(async (tx) => {
            await tx.insert('orders', order.toRecord());
            for (const item of order.items) {
                await tx.insert('order_items', item.toRecord());
            }
        });
        
        // Publish event for read model update
        await this.eventPublisher.publish(new OrderCreatedEvent(order));
        
        return order.id;
    }
}
 
// Read side: Denormalized database (could be different tech)
class OrderQueryService {
    constructor(private readDb: MongoDatabase) {} // Different database!
 
    async getOrderSummaries(customerId: string): Promise<OrderSummaryDto[]> {
        // Query against denormalized collection
        // No JOINs needed—data pre-aggregated
        return this.readDb.find('order_views', { customerId })
            .sort({ createdAt: -1 });
    }
}
 
// Synchronization: Event handler updates read model
class OrderReadModelHandler {
    constructor(private readDb: MongoDatabase) {}
 
    @EventHandler(OrderCreatedEvent)
    async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
        await this.readDb.insert('order_views', {
            orderId: event.orderId,
            customerId: event.customerId,
            status: 'pending',
            itemCount: event.items.length,
            total: event.items.reduce((sum, i) => sum + i.quantity * i.price, 0),
            createdAt: event.timestamp,
        });
    }
}
 
// PROs:
// - Read database optimized for queries
// - Independent scaling of read and write
// - Read model can use different technology
 
// CONs:
// - Eventual consistency between models
// - Synchronization complexity
// - Data duplication

Level 3: Fully Separated Services

The most aggressive form of CQRS: completely separate services for commands and queries, potentially different teams, different deployment pipelines, and entirely different technology stacks.

level-3-cqrs.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
// LEVEL 3: ENTIRELY SEPARATE SERVICES
 
// ===== COMMAND SERVICE (its own microservice) =====
// Technology: Node.js + PostgreSQL
// Team: Order Processing Team
 
@Controller('/api/orders')
class OrderCommandController {
    constructor(private commandBus: CommandBus) {}
 
    @Post('/')
    async createOrder(@Body() request: CreateOrderRequest): Promise<{ orderId: string }> {
        const orderId = await this.commandBus.execute(
            new CreateOrderCommand(request)
        );
        return { orderId };
    }
 
    @Put('/:id/ship')
    async shipOrder(@Param('id') id: string, @Body() request: ShipOrderRequest) {
        await this.commandBus.execute(
            new ShipOrderCommand(id, request.trackingNumber)
        );
    }
}
 
// ===== QUERY SERVICE (completely separate microservice) =====
// Technology: Go + Elasticsearch + Redis
// Team: Customer Experience Team
 
// GetOrderHistory -> queries Elasticsearch for fast search
// GetOrderDetail -> queries Redis for sub-millisecond response
// GetOrderAnalytics -> queries ClickHouse for aggregations
 
@Controller('/api/orders')
class OrderQueryController {
    constructor(
        private elasticsearch: ElasticsearchClient,
        private redis: RedisClient
    ) {}
 
    @Get('/search')
    async searchOrders(@Query() params: OrderSearchParams): Promise<OrderSearchResult> {
        return this.elasticsearch.search('orders', {
            query: this.buildSearchQuery(params),
            sort: [{ createdAt: 'desc' }],
        });
    }
 
    @Get('/:id')
    async getOrderDetail(@Param('id') id: string): Promise<OrderDetailDto> {
        // Sub-millisecond response from Redis
        const cached = await this.redis.get(`order:${id}`);
        if (cached) return JSON.parse(cached);
        
        // Fallback to Elasticsearch if not in cache
        const order = await this.elasticsearch.get('orders', id);
        await this.redis.setex(`order:${id}`, 300, JSON.stringify(order));
        return order;
    }
}
 
// ===== SYNCHRONIZATION SERVICE =====
// Consumes events from command service, updates query stores
 
class OrderProjectionService {
    constructor(
        private elasticsearch: ElasticsearchClient,
        private redis: RedisClient,
        private clickhouse: ClickHouseClient
    ) {}
 
    @EventHandler('order.created')
    async onOrderCreated(event: OrderCreatedEvent) {
        // Update Elasticsearch for search
        await this.elasticsearch.index('orders', event.orderId, {
            orderId: event.orderId,
            customerId: event.customerId,
            status: 'pending',
            // ...
        });
        
        // Update ClickHouse for analytics
        await this.clickhouse.insert('order_events', {
            event_type: 'created',
            order_id: event.orderId,
            timestamp: event.timestamp,
            // ...
        });
        
        // Redis updated on-demand (lazy)
    }
}

CQRS Implementation Levels Comparison
Aspect	Level 1: Same DB	Level 2: Separate Read DB	Level 3: Separate Services
Complexity	Low	Medium	High
Consistency	Strong	Eventual	Eventual
Read Optimization	Limited	High	Maximum
Independent Scaling	No	Yes (data layer)	Yes (complete)
Technology Flexibility	None	Different DBs	Different stacks
Team Independence	Same team	Same team possible	Different teams possible
Operational Overhead	Low	Medium	High
Best For	Simple apps	Read-heavy apps	Enterprise-scale

Start Simple, Evolve as Needed

Begin with Level 1 CQRS (same database, different models). It provides immediate benefits with minimal complexity. Evolve to Level 2 or 3 only when you have concrete evidence that the simpler approach is insufficient. Premature optimization here creates significant operational burden.

When CQRS Makes Sense

CQRS is not a universal solution. It introduces complexity and is only justified when that complexity pays off. Understanding the indicators for and against CQRS is crucial for making sound architectural decisions.

Strong Indicators FOR CQRS:

CQRS is Likely Valuable When...

•Extreme Read/Write Asymmetry — Read operations outnumber writes by 100:1 or more. The overhead of maintaining separate models is justified by the massive read-side optimization potential.
•Complex Domain with Distinct Read Views — The domain model is rich with business logic, but users need multiple, specialized views (dashboards, reports, mobile, admin) that don't map cleanly to domain aggregates.
•Different Consistency Requirements — Writes require strong consistency and transactional guarantees, but reads can tolerate eventual consistency in exchange for better performance and availability.
•Collaborative Domains — Many users edit the same data concurrently. Separating the write model from read views helps manage conflicts and provides each user with responsive reads.
•Integration with Event Sourcing — If you're already using event sourcing, CQRS is almost mandatory. Events are the natural mechanism for synchronizing read models.
•Team Scaling — Large organizations where different teams own the read and write concerns. CQRS provides clear boundaries for independent development.

CQRS is Likely Overkill When...

•Simple CRUD Applications — If your app is primarily data entry and display with minimal business logic, CQRS adds complexity without sufficient benefit.
•Low Traffic Volume — If your system handles tens or hundreds of requests per second, traditional approaches likely suffice. The overhead of maintaining dual models isn't justified.
•Strong Consistency Required Everywhere — If every read must reflect the absolute latest write (e.g., financial reconciliation), the eventual consistency of CQRS read models is problematic.
•Small Team / Solo Developer — The cognitive overhead of maintaining multiple models and synchronization logic can slow down small teams more than it helps.
•Early-Stage Startup — When you're still discovering your domain, CQRS's upfront structure can impede pivoting. Wait until the domain stabilizes.

Good CQRS Candidate

E-commerce product catalog: Millions of read queries per second for product pages, but only hundreds of writes per second for inventory updates. Read model can be a search index (Elasticsearch) while write model uses a relational database with strict transactional controls.

Poor CQRS Candidate

Internal admin tool: 50 users, simple forms, immediate consistency needed for data entry. A traditional CRUD approach with a single database is simpler, easier to maintain, and fully meets requirements.

The Decision Framework:

Before adopting CQRS, answer these questions:

What is my read-to-write ratio? If below 10:1, CQRS may not be justified.
How different are my read shapes from my write shapes? If nearly identical, separate models have little value.
Can I tolerate eventual consistency for reads? If not, CQRS complexity skyrockets.
Do I have the operational capacity for multiple data stores? If not, stick with simpler approaches.
Is my domain stable enough to define separate models? If still evolving rapidly, CQRS will slow pivots.

If you can't answer "yes" to at least three of these, CQRS is probably premature.

Summary: The Foundation of CQRS

We've established the conceptual foundation of Command Query Responsibility Segregation. Let's consolidate the key insights:

Key Takeaways

•CQRS extends CQS to architecture — While CQS separates methods, CQRS separates entire models for reads and writes, potentially using different databases and services.
•Traditional CRUD creates forced compromises — One model trying to serve both reads and writes leads to suboptimal designs for both concerns.
•The core insight is that reads and writes are different problems — They have different consistency requirements, scalability needs, and optimal data shapes.
•CQRS exists on a spectrum — From simple model separation to completely separate services. Choose the level appropriate for your needs.
•CQRS is not universally applicable — It introduces complexity that must be justified by specific characteristics of your system.
•Start simple, evolve as needed — Begin with the simplest form of CQRS and increase separation only when concrete benefits justify the complexity.

What's Next:

In the following pages, we'll dive deeper into the practical aspects of CQRS:

Page 2: Designing effective command and query models
Page 3: Synchronization strategies between read and write models
Page 4: CQRS implementation patterns and anti-patterns
Page 5: Integrating CQRS with Event Sourcing

Page Complete

You now understand the fundamental principle of CQRS: separating command and query responsibilities to optimize each independently. This conceptual foundation is essential for understanding the implementation patterns and practical considerations we'll explore in subsequent pages.

1 / 5

Loading learning content...

System Design (HLD)Distributed Data Patterns

CQRS Pattern

LevelAdvanced

Duration75 mins

TopicDistributed Data Patterns

1 / 5

Command Query Responsibility Segregation - Introduction

The Fundamental Tension in Data Access

Consider an e-commerce platform. When a customer places an order, the system must:

Validate inventory availability
Process payment
Create order records
Update stock levels
Trigger fulfillment workflows

This is a complex, transactional operation requiring strict consistency guarantees. But when the same customer views their order history, the system needs:

Fast response times
The ability to aggregate data from multiple sources
Denormalized views optimized for display
The capacity to serve thousands of concurrent requests

These are fundamentally different problems. Forcing them through the same architecture creates inevitable compromises.

What You Will Learn

Origins and Evolution of CQRS

CQRS didn't emerge in a vacuum—it evolved from decades of software architecture experience. Understanding its lineage helps explain why it exists and where it provides value.

Command Query Separation (CQS): The Intellectual Foundation

Bertrand Meyer, creator of the Eiffel programming language, introduced Command Query Separation (CQS) in the 1980s as a design principle for object-oriented programming:

"Every method should either be a command that performs an action, or a query that returns data to the caller, but not both."

In CQS:

Commands (also called modifiers) change state but return nothing
Queries return data but do not modify state

This principle promotes predictability and reduces side effects. When you call a query method, you know the system state won't change. When you call a command, you know you're triggering a mutation.

cqs-example.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// CQS-COMPLIANT DESIGN
 
class ShoppingCart {
    private items: CartItem[] = [];
 
    // COMMAND: Modifies state, returns nothing
    addItem(product: Product, quantity: number): void {
        const existingItem = this.items.find(i => i.productId === product.id);
        if (existingItem) {
            existingItem.quantity += quantity;
        } else {
            this.items.push({ productId: product.id, quantity, price: product.price });
        }
    }
 
    // COMMAND: Modifies state, returns nothing
    removeItem(productId: string): void {
        this.items = this.items.filter(i => i.productId !== productId);
    }
 
    // QUERY: Returns data, does not modify state
    getTotal(): number {
        return this.items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
    }
 
    // QUERY: Returns data, does not modify state
    getItemCount(): number {
        return this.items.reduce((sum, item) => sum + item.quantity, 0);
    }
 
    // QUERY: Returns data, does not modify state
    getItems(): ReadonlyArray<CartItem> {
        return [...this.items]; // Return copy to prevent mutation
    }
}
 
// CQS VIOLATION (Anti-pattern)
class BadShoppingCart {
    // VIOLATES CQS: Modifies state AND returns data
    addItemAndGetTotal(product: Product, quantity: number): number {
        this.items.push({ productId: product.id, quantity, price: product.price });
        return this.getTotal(); // Mix of command and query
    }
}

From CQS to CQRS: Architectural Evolution

Greg Young, in the mid-2000s, extrapolated Meyer's method-level principle to the architectural level, creating Command Query Responsibility Segregation (CQRS):

"CQS applies to individual methods. CQRS applies to entire system architectures—using different models for commands (writes) and queries (reads)."

This is a crucial distinction. While CQS tells you how to design methods, CQRS tells you how to design systems. The implications are profound:

Aspect	CQS (Method Level)	CQRS (System Level)
Scope	Single object's methods	Entire bounded context
Models	Same object for read/write	Separate read and write models
Storage	Single database table	Potentially separate databases
Optimization	None	Independent optimization of each path
Consistency	Immediate	Can be eventual between models

The Mental Leap

The Problem with Traditional CRUD

The CRUD Mental Model:

┌─────────────────────────────────────────────────────┐
│                   APPLICATION                        │
│  ┌─────────────────────────────────────────────┐    │
│  │            Unified Domain Model              │    │
│  │  (One model handles reads AND writes)        │    │
│  └─────────────────────────────────────────────┘    │
│                        │                             │
│                        ▼                             │
│  ┌─────────────────────────────────────────────┐    │
│  │              Data Access Layer               │    │
│  │  (Same repository for all operations)        │    │
│  └─────────────────────────────────────────────┘    │
│                        │                             │
│                        ▼                             │
│  ┌─────────────────────────────────────────────┐    │
│  │           Single Database Schema             │    │
│  │  (Normalized for writes, queries span joins) │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

This approach works beautifully for simple applications. But as systems grow, inherent tensions emerge:

Inherent Tensions in CRUD Architecture

•Normalization vs. Query Performance — Data is normalized for write efficiency (no redundancy), but reads require expensive JOINs across multiple tables. A product listing page might JOIN products, inventory, pricing, reviews, and seller information.
•Write Validation vs. Read Simplicity — Domain models often contain validation logic, invariant enforcement, and business rules essential for writes—but entirely unnecessary overhead when simply displaying data.
•Transactional Consistency vs. Read Scalability — Write operations require ACID transactions and strong consistency. But read-heavy workloads often benefit from eventual consistency and replicated read models.
•Schema Rigidity vs. View Flexibility — The database schema is optimized for one purpose. But different views need different data shapes—a mobile app might need condensed data while dashboards need aggregations.
•Aggregate Boundaries vs. Query Scope — Domain-Driven Design encourages well-defined aggregate boundaries for writes. But queries frequently need to span multiple aggregates, creating awkward cross-aggregate coordination.

crud-compromise.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
// TRADITIONAL CRUD: ONE MODEL FOR EVERYTHING
 
interface Order {
    id: string;
    customerId: string;
    items: OrderItem[];
    status: OrderStatus;
    shippingAddress: Address;
    billingAddress: Address;
    paymentInfo: PaymentInfo;
    createdAt: Date;
    updatedAt: Date;
    
    // Validation for writes
    validate(): ValidationResult;
    
    // Business logic for state transitions
    canCancel(): boolean;
    cancel(): void;
    
    // Used for display but clutters the write model
    getDisplayTotal(): string;
    getStatusLabel(): string;
}
 
class OrderService {
    // WRITE: Complex validation and business rules
    async createOrder(request: CreateOrderRequest): Promise<Order> {
        const order = new Order(request);
        order.validate(); // Complex validation
        
        // Transaction across multiple aggregates
        await this.beginTransaction();
        await this.inventoryService.reserve(order.items);
        await this.paymentService.authorize(order.paymentInfo);
        await this.orderRepository.save(order);
        await this.commitTransaction();
        
        return order;
    }
    
    // READ: Just needs to display data
    async getOrderHistory(customerId: string): Promise<Order[]> {
        // But we fetch the ENTIRE Order model
        // Including validation logic we won't use
        // Including payment info we don't need to display
        // Requiring JOINs across Order, OrderItem, Address, Payment
        return this.orderRepository.findByCustomerId(customerId);
    }
    
    // THE PROBLEM: getOrderHistory doesn't need:
    // - Validation methods
    // - Full payment details
    // - State transition logic
    // - Shipping calculations
    // 
    // It ONLY needs:
    // - Order ID, date, status
    // - Item summaries
    // - Total amount
    // 
    // But CRUD forces us to use the same model.
}

The Scaling Problem:

In most applications, reads vastly outnumber writes. On a typical e-commerce platform:

Operation Type	Frequency	Characteristics
Page Views (reads)	10,000/second	Simple, cacheable
Searches (reads)	1,000/second	Complex aggregations
Add to Cart (writes)	100/second	Low validation
Place Order (writes)	10/second	High validation, transactional
Update Profile (writes)	1/second	Simple

The read-to-write ratio is often 100:1 or higher. Yet CRUD forces both through the same pipeline, meaning:

Reads are slowed by infrastructure optimized for write consistency
Writes can't be optimized without compromising read performance
Scaling means duplicating everything—even the write-oriented logic you don't need for reads

The One-Model Fallacy

The CQRS Core Principle

The CQRS Mental Model:

┌────────────────────────────────────────────────────────────────┐
│                       APPLICATION                               │
│                                                                  │
│   ╔══════════════════════╗      ╔══════════════════════╗        │
│   ║    COMMAND SIDE      ║      ║     QUERY SIDE       ║        │
│   ║                      ║      ║                      ║        │
│   ║  ┌────────────────┐  ║      ║  ┌────────────────┐  ║        │
│   ║  │ Command Model  │  ║      ║  │  Query Model   │  ║        │
│   ║  │ (Rich Domain)  │  ║      ║  │  (Read DTOs)   │  ║        │
│   ║  └───────┬────────┘  ║      ║  └───────▲────────┘  ║        │
│   ║          │           ║      ║          │           ║        │
│   ║  ┌───────▼────────┐  ║      ║  ┌───────┴────────┐  ║        │
│   ║  │ Write Database │  ║─────▶║  │ Read Database  │  ║        │
│   ║  │ (Normalized)   │  ║ sync ║  │ (Denormalized) │  ║        │
│   ║  └────────────────┘  ║      ║  └────────────────┘  ║        │
│   ╚══════════════════════╝      ╚══════════════════════╝        │
│                                                                  │
└────────────────────────────────────────────────────────────────┘

Core CQRS Principles

•Separate Models — Commands use a rich domain model focused on business rules and invariant protection. Queries use lean DTOs optimized purely for display.
•Separate Paths — Commands and queries follow completely different code paths. They may share no infrastructure beyond the synchronization mechanism.
•Independent Optimization — The command side can use a normalized relational database. The query side can use denormalized read replicas, search indices, or materialized views.
•Independent Scaling — Read and write infrastructure scale independently. A 100:1 read-to-write ratio means 100x more query capacity—without scaling write infrastructure.
•Eventual Consistency (Optional) — The read model may lag behind the write model. This enables asynchronous synchronization and better fault isolation.

cqrs-architecture.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
// ========================================
// COMMAND SIDE: RICH DOMAIN MODEL
// ========================================
 
// Domain aggregate with full business logic
class Order {
    private id: OrderId;
    private items: OrderItem[];
    private status: OrderStatus;
    private events: DomainEvent[] = [];
 
    constructor(customerId: CustomerId, items: OrderItemRequest[]) {
        this.validate(items);
        this.id = OrderId.generate();
        this.items = items.map(i => OrderItem.create(i));
        this.status = OrderStatus.PENDING;
        this.events.push(new OrderCreatedEvent(this.id, customerId, items));
    }
 
    private validate(items: OrderItemRequest[]): void {
        if (items.length === 0) throw new EmptyOrderError();
        if (items.some(i => i.quantity <= 0)) throw new InvalidQuantityError();
        // Complex validation logic...
    }
 
    ship(trackingNumber: string): void {
        if (this.status !== OrderStatus.CONFIRMED) {
            throw new InvalidStateTransitionError('Cannot ship unconfirmed order');
        }
        this.status = OrderStatus.SHIPPED;
        this.events.push(new OrderShippedEvent(this.id, trackingNumber));
    }
 
    cancel(reason: string): void {
        if (!this.canCancel()) {
            throw new InvalidStateTransitionError('Order cannot be cancelled');
        }
        this.status = OrderStatus.CANCELLED;
        this.events.push(new OrderCancelledEvent(this.id, reason));
    }
 
    private canCancel(): boolean {
        return [OrderStatus.PENDING, OrderStatus.CONFIRMED].includes(this.status);
    }
 
    getDomainEvents(): DomainEvent[] {
        return [...this.events];
    }
}
 
// Command handler
class CreateOrderHandler {
    constructor(
        private orderRepository: OrderRepository,
        private eventBus: EventBus
    ) {}
 
    async handle(command: CreateOrderCommand): Promise<OrderId> {
        // Create domain aggregate (validation happens here)
        const order = new Order(command.customerId, command.items);
        
        // Persist to write database
        await this.orderRepository.save(order);
        
        // Publish events for read model synchronization
        await this.eventBus.publish(order.getDomainEvents());
        
        return order.id;
    }
}
 
// ========================================
// QUERY SIDE: LEAN READ MODELS
// ========================================
 
// Read model: Just data, no behavior
interface OrderSummaryDto {
    orderId: string;
    customerName: string;
    itemCount: number;
    totalAmount: number;
    status: string;
    createdAt: string;
}
 
interface OrderDetailDto {
    orderId: string;
    customerName: string;
    items: Array<{
        productName: string;
        quantity: number;
        unitPrice: number;
        lineTotal: number;
    }>;
    subtotal: number;
    tax: number;
    shipping: number;
    total: number;
    status: string;
    timeline: Array<{
        status: string;
        timestamp: string;
    }>;
}
 
// Query handler: Direct database queries, no domain logic
class OrderQueryHandler {
    constructor(private readDatabase: ReadDatabase) {}
 
    async getOrderHistory(customerId: string): Promise<OrderSummaryDto[]> {
        // Direct query against denormalized read model
        // No JOINs needed—data already in optimal shape
        return this.readDatabase.query(`
            SELECT order_id, customer_name, item_count, 
                   total_amount, status, created_at
            FROM order_summaries
            WHERE customer_id = $1
            ORDER BY created_at DESC
        `, [customerId]);
    }
 
    async getOrderDetail(orderId: string): Promise<OrderDetailDto> {
        // Pre-computed and stored in optimal format
        return this.readDatabase.queryOne(`
            SELECT * FROM order_details WHERE order_id = $1
        `, [orderId]);
    }
}
 
// ========================================
// SYNCHRONIZATION: CONNECTING THE MODELS
// ========================================
 
class OrderReadModelProjection {
    constructor(private readDatabase: ReadDatabase) {}
 
    async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
        // Project domain event into read model
        await this.readDatabase.upsert('order_summaries', {
            order_id: event.orderId,
            customer_id: event.customerId,
            customer_name: await this.lookupCustomerName(event.customerId),
            item_count: event.items.length,
            total_amount: this.calculateTotal(event.items),
            status: 'Pending',
            created_at: event.timestamp,
        });
 
        await this.readDatabase.upsert('order_details', {
            order_id: event.orderId,
            // ... full detail projection
        });
    }
 
    async handleOrderShipped(event: OrderShippedEvent): Promise<void> {
        await this.readDatabase.update('order_summaries', 
            { order_id: event.orderId },
            { status: 'Shipped' }
        );
        
        await this.readDatabase.appendToTimeline('order_details',
            event.orderId,
            { status: 'Shipped', timestamp: event.timestamp }
        );
    }
}

The Conceptual Leap

Types of CQRS Implementation

CQRS exists on a spectrum. Not all implementations require separate databases or complex event systems. Understanding the options helps you choose the right level of separation for your needs.

Level 1: Same Database, Different Models

The simplest form of CQRS uses the same database but different code paths. Commands use rich domain objects; queries use lightweight query services that return DTOs directly.

level-1-cqrs.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// LEVEL 1: SAME DATABASE, DIFFERENT MODELS
 
// Command side: Uses ORM with full domain model
class OrderCommandService {
    async createOrder(command: CreateOrderCommand): Promise<string> {
        const order = new Order(command);
        await this.orderRepository.save(order); // ORM persistence
        return order.id;
    }
}
 
// Query side: Direct SQL, bypassing ORM entirely
class OrderQueryService {
    async getOrderSummaries(customerId: string): Promise<OrderSummaryDto[]> {
        // Direct database query—no ORM, no domain objects
        return this.database.query(`
            SELECT 
                o.id as order_id,
                o.created_at,
                o.status,
                COUNT(oi.id) as item_count,
                SUM(oi.quantity * oi.unit_price) as total
            FROM orders o
            LEFT JOIN order_items oi ON oi.order_id = o.id
            WHERE o.customer_id = $1
            GROUP BY o.id
            ORDER BY o.created_at DESC
        `, [customerId]);
    }
}
 
// PROs:
// - Simple to implement
// - Single source of truth
// - Strong consistency
// - No synchronization needed
 
// CONs:
// - Query performance limited by normalized schema
// - Same database handles both loads
// - Read and write scaling tied together

Level 2: Separate Read Database

The query side reads from a separate database optimized for reads. Changes from the write database are synchronized (often asynchronously) to the read database.

level-2-cqrs.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
// LEVEL 2: SEPARATE READ DATABASE
 
// Write side: Relational database with normalized schema
class OrderCommandService {
    constructor(
        private writeDb: PostgresDatabase,
        private eventPublisher: EventPublisher
    ) {}
 
    async createOrder(command: CreateOrderCommand): Promise<string> {
        const order = new Order(command);
        
        await this.writeDb.transaction(async (tx) => {
            await tx.insert('orders', order.toRecord());
            for (const item of order.items) {
                await tx.insert('order_items', item.toRecord());
            }
        });
        
        // Publish event for read model update
        await this.eventPublisher.publish(new OrderCreatedEvent(order));
        
        return order.id;
    }
}
 
// Read side: Denormalized database (could be different tech)
class OrderQueryService {
    constructor(private readDb: MongoDatabase) {} // Different database!
 
    async getOrderSummaries(customerId: string): Promise<OrderSummaryDto[]> {
        // Query against denormalized collection
        // No JOINs needed—data pre-aggregated
        return this.readDb.find('order_views', { customerId })
            .sort({ createdAt: -1 });
    }
}
 
// Synchronization: Event handler updates read model
class OrderReadModelHandler {
    constructor(private readDb: MongoDatabase) {}
 
    @EventHandler(OrderCreatedEvent)
    async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
        await this.readDb.insert('order_views', {
            orderId: event.orderId,
            customerId: event.customerId,
            status: 'pending',
            itemCount: event.items.length,
            total: event.items.reduce((sum, i) => sum + i.quantity * i.price, 0),
            createdAt: event.timestamp,
        });
    }
}
 
// PROs:
// - Read database optimized for queries
// - Independent scaling of read and write
// - Read model can use different technology
 
// CONs:
// - Eventual consistency between models
// - Synchronization complexity
// - Data duplication

Level 3: Fully Separated Services

The most aggressive form of CQRS: completely separate services for commands and queries, potentially different teams, different deployment pipelines, and entirely different technology stacks.

level-3-cqrs.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
// LEVEL 3: ENTIRELY SEPARATE SERVICES
 
// ===== COMMAND SERVICE (its own microservice) =====
// Technology: Node.js + PostgreSQL
// Team: Order Processing Team
 
@Controller('/api/orders')
class OrderCommandController {
    constructor(private commandBus: CommandBus) {}
 
    @Post('/')
    async createOrder(@Body() request: CreateOrderRequest): Promise<{ orderId: string }> {
        const orderId = await this.commandBus.execute(
            new CreateOrderCommand(request)
        );
        return { orderId };
    }
 
    @Put('/:id/ship')
    async shipOrder(@Param('id') id: string, @Body() request: ShipOrderRequest) {
        await this.commandBus.execute(
            new ShipOrderCommand(id, request.trackingNumber)
        );
    }
}
 
// ===== QUERY SERVICE (completely separate microservice) =====
// Technology: Go + Elasticsearch + Redis
// Team: Customer Experience Team
 
// GetOrderHistory -> queries Elasticsearch for fast search
// GetOrderDetail -> queries Redis for sub-millisecond response
// GetOrderAnalytics -> queries ClickHouse for aggregations
 
@Controller('/api/orders')
class OrderQueryController {
    constructor(
        private elasticsearch: ElasticsearchClient,
        private redis: RedisClient
    ) {}
 
    @Get('/search')
    async searchOrders(@Query() params: OrderSearchParams): Promise<OrderSearchResult> {
        return this.elasticsearch.search('orders', {
            query: this.buildSearchQuery(params),
            sort: [{ createdAt: 'desc' }],
        });
    }
 
    @Get('/:id')
    async getOrderDetail(@Param('id') id: string): Promise<OrderDetailDto> {
        // Sub-millisecond response from Redis
        const cached = await this.redis.get(`order:${id}`);
        if (cached) return JSON.parse(cached);
        
        // Fallback to Elasticsearch if not in cache
        const order = await this.elasticsearch.get('orders', id);
        await this.redis.setex(`order:${id}`, 300, JSON.stringify(order));
        return order;
    }
}
 
// ===== SYNCHRONIZATION SERVICE =====
// Consumes events from command service, updates query stores
 
class OrderProjectionService {
    constructor(
        private elasticsearch: ElasticsearchClient,
        private redis: RedisClient,
        private clickhouse: ClickHouseClient
    ) {}
 
    @EventHandler('order.created')
    async onOrderCreated(event: OrderCreatedEvent) {
        // Update Elasticsearch for search
        await this.elasticsearch.index('orders', event.orderId, {
            orderId: event.orderId,
            customerId: event.customerId,
            status: 'pending',
            // ...
        });
        
        // Update ClickHouse for analytics
        await this.clickhouse.insert('order_events', {
            event_type: 'created',
            order_id: event.orderId,
            timestamp: event.timestamp,
            // ...
        });
        
        // Redis updated on-demand (lazy)
    }
}

CQRS Implementation Levels Comparison
Aspect	Level 1: Same DB	Level 2: Separate Read DB	Level 3: Separate Services
Complexity	Low	Medium	High
Consistency	Strong	Eventual	Eventual
Read Optimization	Limited	High	Maximum
Independent Scaling	No	Yes (data layer)	Yes (complete)
Technology Flexibility	None	Different DBs	Different stacks
Team Independence	Same team	Same team possible	Different teams possible
Operational Overhead	Low	Medium	High
Best For	Simple apps	Read-heavy apps	Enterprise-scale

Start Simple, Evolve as Needed

When CQRS Makes Sense

Strong Indicators FOR CQRS:

CQRS is Likely Valuable When...

•Extreme Read/Write Asymmetry — Read operations outnumber writes by 100:1 or more. The overhead of maintaining separate models is justified by the massive read-side optimization potential.
•Complex Domain with Distinct Read Views — The domain model is rich with business logic, but users need multiple, specialized views (dashboards, reports, mobile, admin) that don't map cleanly to domain aggregates.
•Different Consistency Requirements — Writes require strong consistency and transactional guarantees, but reads can tolerate eventual consistency in exchange for better performance and availability.
•Collaborative Domains — Many users edit the same data concurrently. Separating the write model from read views helps manage conflicts and provides each user with responsive reads.
•Integration with Event Sourcing — If you're already using event sourcing, CQRS is almost mandatory. Events are the natural mechanism for synchronizing read models.
•Team Scaling — Large organizations where different teams own the read and write concerns. CQRS provides clear boundaries for independent development.

CQRS is Likely Overkill When...

•Simple CRUD Applications — If your app is primarily data entry and display with minimal business logic, CQRS adds complexity without sufficient benefit.
•Low Traffic Volume — If your system handles tens or hundreds of requests per second, traditional approaches likely suffice. The overhead of maintaining dual models isn't justified.
•Strong Consistency Required Everywhere — If every read must reflect the absolute latest write (e.g., financial reconciliation), the eventual consistency of CQRS read models is problematic.
•Small Team / Solo Developer — The cognitive overhead of maintaining multiple models and synchronization logic can slow down small teams more than it helps.
•Early-Stage Startup — When you're still discovering your domain, CQRS's upfront structure can impede pivoting. Wait until the domain stabilizes.

Good CQRS Candidate

Poor CQRS Candidate

The Decision Framework:

Before adopting CQRS, answer these questions:

What is my read-to-write ratio? If below 10:1, CQRS may not be justified.
How different are my read shapes from my write shapes? If nearly identical, separate models have little value.
Can I tolerate eventual consistency for reads? If not, CQRS complexity skyrockets.
Do I have the operational capacity for multiple data stores? If not, stick with simpler approaches.
Is my domain stable enough to define separate models? If still evolving rapidly, CQRS will slow pivots.

If you can't answer "yes" to at least three of these, CQRS is probably premature.

Summary: The Foundation of CQRS

We've established the conceptual foundation of Command Query Responsibility Segregation. Let's consolidate the key insights:

Key Takeaways

•CQRS extends CQS to architecture — While CQS separates methods, CQRS separates entire models for reads and writes, potentially using different databases and services.
•Traditional CRUD creates forced compromises — One model trying to serve both reads and writes leads to suboptimal designs for both concerns.
•The core insight is that reads and writes are different problems — They have different consistency requirements, scalability needs, and optimal data shapes.
•CQRS exists on a spectrum — From simple model separation to completely separate services. Choose the level appropriate for your needs.
•CQRS is not universally applicable — It introduces complexity that must be justified by specific characteristics of your system.
•Start simple, evolve as needed — Begin with the simplest form of CQRS and increase separation only when concrete benefits justify the complexity.

What's Next:

In the following pages, we'll dive deeper into the practical aspects of CQRS:

Page 2: Designing effective command and query models
Page 3: Synchronization strategies between read and write models
Page 4: CQRS implementation patterns and anti-patterns
Page 5: Integrating CQRS with Event Sourcing

Page Complete

1 / 5