2nd/10_Wiki/Topics/Coding/Backend_CQRS_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
backend-cqrs-patterns	CQRS — 명령 / 조회 분리	Coding	draft	B	conceptual	2026-05-09	2026-05-09	backend cqrs ddd vibe-coding	language applicable_to TS / SQL Backend		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 분리

// 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 (정확)

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 (빠른)

-- 미리 계산된 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)

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)

-- 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 처리

// 사용자가 만든 후 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