[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/DB_Read_Replica_Patterns.md

@@ -0,0 +1,141 @@
+---
+id: db-read-replica-patterns
+title: Read Replica — Replication Lag / 일관성
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [database, replication, read-replica, consistency, vibe-coding]
+tech_stack: { language: "SQL / Postgres / MySQL", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [replication lag, eventual consistency, write-then-read, read-your-writes]
+---
+
+# Read Replica
+
+> Primary 1대 + Replica N대. Read 분산 → Primary 부하↓. **Replication lag (보통 ms~s) 이 함정**. 방금 쓴 데이터 즉시 read 시 미반영 가능 — read-your-writes 패턴 필요.
+
+## 📖 핵심 개념
+- Async replication (보통): primary 가 commit 후 replica 로 stream.
+- Replication lag: primary→replica 도달 시간.
+- Read-your-writes: 자기가 쓴 건 자기가 읽을 때 보여야.
+- Strong vs eventual: 모든 쿼리가 강할 필요 없음.
+
+## 💻 코드 패턴
+
+### 라우팅 — Prisma
+```ts
+import { PrismaClient } from '@prisma/client';
+
+const writer = new PrismaClient({ datasources: { db: { url: process.env.PRIMARY_URL } } });
+const reader = new PrismaClient({ datasources: { db: { url: process.env.REPLICA_URL } } });
+
+async function getUserPosts(userId: string) {
+  return reader.post.findMany({ where: { userId } }); // read = replica
+}
+
+async function createPost(input: NewPost) {
+  return writer.post.create({ data: input }); // write = primary
+}
+```
+
+### Read-your-writes — sticky after write
+```ts
+class DbRouter {
+  private lastWriteAt = 0;
+
+  reader() {
+    if (Date.now() - this.lastWriteAt < 2000) return writer; // 최근 2초 = primary
+    return reader;
+  }
+
+  async write(fn: (db) => Promise<void>) {
+    await fn(writer);
+    this.lastWriteAt = Date.now();
+  }
+}
+```
+
+### 좀 더 정확 — LSN tracking (Postgres)
+```sql
+-- Primary 에서 commit 후 LSN 받음
+SELECT pg_current_wal_lsn();
+
+-- Replica 에서 검사
+SELECT pg_last_wal_replay_lsn() >= 'X/Y'::pg_lsn AS caught_up;
+```
+
+```ts
+async function readAfterWrite(query: () => Promise<R>): Promise<R> {
+  const lsn = await writer.queryRaw('SELECT pg_current_wal_lsn() AS lsn');
+  
+  for (let i = 0; i < 10; i++) {
+    const caught = await reader.queryRaw(
+      `SELECT pg_last_wal_replay_lsn() >= '${lsn}'::pg_lsn AS ok`
+    );
+    if (caught.ok) return query.call(reader);
+    await sleep(50);
+  }
+  return query.call(writer); // fallback
+}
+```
+
+### 라우팅 — request scope
+```ts
+// Express middleware
+app.use((req, res, next) => {
+  req.db = req.method === 'GET' ? reader : writer;
+  next();
+});
+```
+
+### 트랜잭션 안 — primary 만
+```ts
+// 트랜잭션 내 read 도 primary — replica 는 다른 view 가능
+await writer.$transaction(async (tx) => {
+  const user = await tx.user.findUnique(...);   // primary
+  await tx.post.create({ data: { userId: user.id, ...} });
+});
+```
+
+### Replication lag 모니터링
+```sql
+-- Postgres
+SELECT now() - pg_last_xact_replay_timestamp() AS lag;
+
+-- MySQL
+SHOW REPLICA STATUS\G
+-- Seconds_Behind_Source
+```
+
+알람: lag > 5s.
+
+## 🤔 의사결정 기준
+| 상황 | 라우팅 |
+|---|---|
+| Write | Primary |
+| 즉시 read after write | Primary (2초 sticky) |
+| 일반 list / detail | Replica |
+| 분석 / 리포트 | Replica (분리된 분석용) |
+| 트랜잭션 내 read | Primary (같은 connection) |
+| Cache 가능 | Cache 우선, 미스 시 replica |
+
+## ❌ 안티패턴
+- **모든 read 를 무조건 replica**: read-after-write 깨짐.
+- **트랜잭션 안 read 를 replica**: stale.
+- **Lag 모니터링 없음**: 100s lag 도 모름.
+- **Replica failover 안 함**: replica 1대 죽으면 모두 실패. health check + 다음 replica.
+- **Primary write 성공 → 그 자리에서 replica read**: 거의 무조건 stale.
+- **GROUP BY count 같은 무거운 쿼리 primary**: primary 부하. analytic replica 분리.
+
+## 🤖 LLM 활용 힌트
+- 기본 read = replica, write = primary.
+- Read-your-writes = 2초 sticky 또는 LSN.
+- Lag 모니터링 + alarm 필수.
+
+## 🔗 관련 문서
+- [[DB_Connection_Pooling_Patterns]]
+- [[DB_Sharding_Strategies]]
+- [[Caching_Strategies]]