2nd/10_Wiki/Topic_Programming/Coding/DB_Distributed_Locks.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
db-distributed-locks	Distributed Locks — Redis / DB / ZooKeeper	Coding	draft	B	conceptual	2026-05-09	2026-05-09	database redis lock distributed vibe-coding	language applicable_to TS / Redis / Postgres Backend		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 (단순)

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)

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)

-- 자동 release on tx end
SELECT pg_advisory_xact_lock(hashtext('process-order:42'));
-- 작업
COMMIT;

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)

SELECT pg_try_advisory_lock(42);  -- bigint key
-- 작업
SELECT pg_advisory_unlock(42);

Lease + auto-renew

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

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 — 락 없이

UPDATE orders SET status = 'shipped', version = version + 1
WHERE id = $1 AND version = $expectedVersion;
-- affected rows = 0 → 다른 process 가 변경 → 재시도

Election (단일 leader)

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