[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/DB_Distributed_Locks.md

@@ -0,0 +1,175 @@
+---
+id: db-distributed-locks
+title: Distributed Locks — Redis / DB / ZooKeeper
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [database, redis, lock, distributed, vibe-coding]
+tech_stack: { language: "TS / Redis / Postgres", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [distributed lock, Redlock, advisory lock, leader election, mutex]
+---
+
+# Distributed Locks
+
+> N대 서버가 동시 처리 안 되도록 1개만 작업. **TTL + lease + idempotency**. Redis Redlock / Postgres advisory lock / ZooKeeper. 짧은 critical section + 멱등이 안전.
+
+## 📖 핵심 개념
+- TTL: 락 시간 제한 — crash 시 영원 X.
+- Lease: 보유자가 주기적 갱신.
+- Fencing token: 락 받을 때마다 증가하는 ID — old holder 차단.
+- Optimistic lock: 락 안 잡고 version check.
+
+## 💻 코드 패턴
+
+### Redis SETNX (단순)
+```ts
+async function acquire(key: string, ttlMs: number): Promise<string | null> {
+  const token = crypto.randomUUID();
+  const ok = await redis.set(`lock:${key}`, token, 'PX', ttlMs, 'NX');
+  return ok ? token : null;
+}
+
+// 안전 release (자기 거 만 풀기)
+const RELEASE_LUA = `
+  if redis.call("get", KEYS[1]) == ARGV[1] then
+    return redis.call("del", KEYS[1])
+  else
+    return 0
+  end
+`;
+async function release(key: string, token: string) {
+  await redis.eval(RELEASE_LUA, 1, `lock:${key}`, token);
+}
+```
+
+### Redlock (multi-node Redis)
+```ts
+import Redlock from 'redlock';
+
+const redlock = new Redlock([redisA, redisB, redisC], {
+  retryCount: 5,
+  retryDelay: 200,
+  driftFactor: 0.01,
+});
+
+const lock = await redlock.acquire(['locks:report'], 30_000);
+try {
+  await runReport();
+} finally {
+  await lock.release();
+}
+```
+
+### Postgres advisory lock (transaction-scoped)
+```sql
+-- 자동 release on tx end
+SELECT pg_advisory_xact_lock(hashtext('process-order:42'));
+-- 작업
+COMMIT;
+```
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.queryRaw`SELECT pg_advisory_xact_lock(hashtext(${`process-order:${id}`}))`;
+  await processOrder(tx, id);
+});
+```
+
+### Postgres advisory lock (session-scoped)
+```sql
+SELECT pg_try_advisory_lock(42);  -- bigint key
+-- 작업
+SELECT pg_advisory_unlock(42);
+```
+
+### Lease + auto-renew
+```ts
+class Lease {
+  private timer?: NodeJS.Timeout;
+  constructor(private key: string, private token: string, private ttlMs: number) {
+    this.start();
+  }
+  private start() {
+    this.timer = setInterval(async () => {
+      await redis.eval(EXTEND_LUA, 1, `lock:${this.key}`, this.token, this.ttlMs);
+    }, this.ttlMs * 0.5);
+  }
+  async release() {
+    clearInterval(this.timer);
+    await release(this.key, this.token);
+  }
+}
+```
+
+EXTEND_LUA: token 일치할 때만 PEXPIRE.
+
+### Fencing token
+```ts
+async function acquireWithToken(key: string, ttlMs: number) {
+  const fenceLua = `
+    local cur = redis.call("get", KEYS[1])
+    if not cur or redis.call("ttl", KEYS[1]) < 0 then
+      local fence = redis.call("incr", KEYS[2])
+      redis.call("set", KEYS[1], ARGV[1], "PX", ARGV[2])
+      return fence
+    end
+    return 0
+  `;
+  const fence = await redis.eval(fenceLua, 2, `lock:${key}`, `fence:${key}`, token, ttlMs);
+  return fence > 0 ? { token, fence } : null;
+}
+
+// 외부 시스템에 fence 같이 보내 — 더 큰 fence 만 accept
+```
+
+### Optimistic — 락 없이
+```sql
+UPDATE orders SET status = 'shipped', version = version + 1
+WHERE id = $1 AND version = $expectedVersion;
+-- affected rows = 0 → 다른 process 가 변경 → 재시도
+```
+
+### Election (단일 leader)
+```ts
+async function tryBecomeLeader(): Promise<boolean> {
+  const ok = await redis.set('leader', hostname(), 'EX', 30, 'NX');
+  if (ok) {
+    setInterval(() => redis.expire('leader', 30), 10_000); // refresh
+    return true;
+  }
+  return false;
+}
+```
+
+## 🤔 의사결정 기준
+| 상황 | 추천 |
+|---|---|
+| 단일 DB 내 | Postgres advisory lock |
+| Redis 있음 + 단일 노드 | Redis SETNX |
+| Multi-Redis HA | Redlock |
+| 리더 선출 | etcd / ZooKeeper / Consul / Redis lease |
+| Idempotent 가능 | Optimistic version check |
+| Cron leader 1개만 | DB row lock 또는 Redis lease |
+
+## ❌ 안티패턴
+- **TTL 없음**: holder crash 시 영원 락.
+- **TTL < 작업 시간**: 다른 process 가 동시에 — race.
+- **Token 없는 release**: 다른 holder 의 락 풀어줌.
+- **Redlock 단일 Redis 가정**: HA 없으면 의미 없음.
+- **Lock + 외부 부수효과 + 락 만료**: fence 없으면 두 번 실행.
+- **Lock 잡고 길게 (DB query 포함)**: 다른 work 차단.
+- **Distributed lock 으로 정확성 보장**: 성능 / 실수 방지지, 정확성은 idempotency.
+
+## 🤖 LLM 활용 힌트
+- TTL + token + Lua 안전 release.
+- Postgres advisory = 가장 단순 + 안전 (단일 DB).
+- 정확성 = 락 + idempotency 양쪽.
+
+## 🔗 관련 문서
+- [[Backend_Cron_Patterns]]
+- [[Backend_Idempotency_Keys]]
+- [[Optimistic_Concurrency_Control]]