---
id: backend-cqrs-patterns
title: CQRS — 명령 / 조회 분리
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [backend, cqrs, ddd, vibe-coding]
tech_stack: { language: "TS / SQL", applicable_to: ["Backend"] }
applied_in: []
aliases: [CQRS, command query separation, read model, write model]
---

# CQRS

> **Command (write)** 와 **Query (read)** 를 다른 모델 / 다른 DB / 다른 API. 단순한 read model 로 빠른 query, 정확한 write model 로 일관성. ES 와 자주 페어 — 그러나 ES 없이도 가능.

## 📖 핵심 개념
- Command: 쓰기 (CreateOrder). 모델 = Aggregate.
- Query: 읽기. 모델 = denormalized view.
- Eventual consistency: write → projection 까지 ms~s 지연.

## 💻 코드 패턴

### Command vs Query API 분리
```ts
// commands.ts
async function createOrder(cmd: CreateOrderCommand): Promise<OrderId> { ... }
async function shipOrder(cmd: ShipOrderCommand): Promise<void> { ... }

// queries.ts
async function getOrderSummary(id: OrderId): Promise<OrderSummary> { ... } // 읽기 전용 view
async function listOrdersForUser(userId: UserId): Promise<OrderListItem[]> { ... }
```

### Write side (정확)
```ts
async function createOrder(cmd: CreateOrderCommand) {
  return db.transaction(async (tx) => {
    const order = OrderAggregate.create(cmd);
    await tx.orders.insert(order.toRow());
    await publishEvent(new OrderCreated(order.id, ...));
  });
}
```

### Read side (빠른)
```sql
-- 미리 계산된 view (denormalized)
CREATE TABLE order_summary (
  order_id UUID PRIMARY KEY,
  user_email TEXT,            -- join 안 해도 됨
  user_name TEXT,
  item_count INT,
  total_amount NUMERIC,
  status TEXT,
  created_at TIMESTAMPTZ,
  ...
);

-- 1 query 로 끝
SELECT * FROM order_summary WHERE user_id = $1;
```

### Projection (write events → read view)
```ts
async function projectOrderEvent(e: OrderEvent) {
  switch (e.type) {
    case 'OrderCreated':
      const user = await getUserView(e.userId);
      await db.orderSummary.insert({
        orderId: e.orderId,
        userEmail: user.email, userName: user.name,
        itemCount: 0, totalAmount: 0,
        status: 'open',
        createdAt: e.createdAt,
      });
      break;
    case 'ItemAdded':
      await db.orderSummary.update(e.orderId, {
        itemCount: { increment: 1 },
        totalAmount: { increment: e.price * e.qty },
      });
      break;
    case 'OrderShipped':
      await db.orderSummary.update(e.orderId, { status: 'shipped' });
      break;
  }
}
```

### 다른 DB (read 최적화)
- Write: Postgres (정확).
- Read: Elasticsearch (검색) / DynamoDB (key 검색) / Redis (cache).
- 동기화 = projection / CDC (Debezium).

### Read replica + materialized view (가벼운 CQRS)
```sql
-- Postgres materialized view
CREATE MATERIALIZED VIEW order_summary AS
SELECT o.id, u.email, u.name, count(i) AS item_count, ...
FROM orders o JOIN users u ON ... LEFT JOIN items i ON ...
GROUP BY o.id, u.email, u.name;

-- 주기적 refresh
REFRESH MATERIALIZED VIEW CONCURRENTLY order_summary;
```

### API 분리 (다른 endpoint / service)
```
POST /api/orders           → Command service
GET  /api/orders/:id       → Query service (다른 cluster, 다른 cache)
```

### Eventual consistency 처리
```ts
// 사용자가 만든 후 list 에서 안 보일 수 있음
await api.orders.create(input);
// 즉시 navigate('/orders') → 새 order 안 보임 (projection 늦음)

// 해결: optimistic (TanStack Query setQueryData)
qc.setQueryData(['orders', userId], (old) => [...old, new]);
```

## 🤔 의사결정 기준
| 상황 | 추천 |
|---|---|
| Read >> Write (10:1 이상) | CQRS read 분리 |
| 검색 / 필터 복잡 | CQRS + Elasticsearch |
| 실시간 보장 필요 | CQRS 비추 (eventual consistency) |
| ES 사용 중 | CQRS 자연 |
| 단순 CRUD | 과잉 |
| 보고서 / 분석 | Read replica 또는 OLAP DB |

## ❌ 안티패턴
- **Eventual consistency 모름**: 사용자가 자기 거 못 봄.
- **Read 와 Write 가 같은 모델 — CQRS 흉내**: 분리 의미 없음.
- **Projection lag 모니터링 없음**: 1시간 lag 도 모름.
- **Write 가 read 도 직접 query**: 일관성 깨짐.
- **너무 많은 read view**: 동기화 부담.
- **Replay 불가 (이벤트 누락)**: ES + replay 가 안전.
- **Strong consistency 가정 한 곳**: read-after-write 사용자 불일치.

## 🤖 LLM 활용 힌트
- Read >> Write 일 때 도입.
- Materialized view 가 가장 가벼운 CQRS.
- 진짜 분리 = ES + projection.

## 🔗 관련 문서
- [[Backend_Event_Sourcing]]
- [[DB_Read_Replica_Patterns]]
- [[Backend_Outbox_Pattern]]