Distributed Locks
Coordinate exclusive access to resources across multiple service instances.
Overview
- Preventing duplicate processing of jobs/events
- Coordinating singleton processes (cron, leaders)
- Protecting critical sections across instances
- Implementing leader election
- Rate limiting at distributed level
Lock Types Comparison
| Lock Type | Durability | Latency | Use Case |
|---|---|---|---|
| Redis (single) | Low | ~1ms | Fast, non-critical |
| Redlock (multi) | High | ~5ms | Critical, HA required |
| PostgreSQL advisory | High | ~2ms | Already using PG, ACID |
Quick Reference
Redis Lock (Single Node)
from uuid_utils import uuid7
import redis.asyncio as redis
class RedisLock:
"""Redis lock with Lua scripts for atomicity."""
ACQUIRE = "if redis.call('set',KEYS[1],ARGV[1],'NX','PX',ARGV[2]) then return 1 end return 0"
RELEASE = "if redis.call('get',KEYS[1])==ARGV[1] then return redis.call('del',KEYS[1]) end return 0"
def __init__(self, client: redis.Redis, name: str, ttl_ms: int = 30000):
self._client = client
self._name = f"lock:{name}"
self._owner = str(uuid7())
self._ttl = ttl_ms
async def acquire(self) -> bool:
return await self._client.eval(self.ACQUIRE, 1, self._name, self._owner, self._ttl) == 1
async def release(self) -> bool:
return await self._client.eval(self.RELEASE, 1, self._name, self._owner) == 1
async def __aenter__(self):
if not await self.acquire():
raise LockError(f"Failed to acquire {self._name}")
return self
async def __aexit__(self, *_):
await self.release()See redis-locks.md for complete implementation with retry/extend.
PostgreSQL Advisory Lock
from sqlalchemy import text
async def with_advisory_lock(session, lock_id: int):
"""PostgreSQL advisory lock (session-level)."""
await session.execute(text("SELECT pg_advisory_lock(:id)"), {"id": lock_id})
try:
yield
finally:
await session.execute(text("SELECT pg_advisory_unlock(:id)"), {"id": lock_id})See postgres-advisory-locks.md for transaction-level and monitoring.
Key Decisions
| Decision | Recommendation |
|---|---|
| Backend | Redis for speed, PG if already using it |
| TTL | 2-3x expected operation time |
| Retry | Exponential backoff with jitter |
| Fencing | Include owner ID for safety |
Anti-Patterns (FORBIDDEN)
# NEVER forget TTL (causes deadlocks)
await redis.set(f"lock:{name}", "1") # WRONG - no expiry!
# NEVER release without owner check
await redis.delete(f"lock:{name}") # WRONG - might release others' lock
# NEVER use single Redis for critical operations
lock = RedisLock(single_redis, "payment") # Use Redlock for HA
# NEVER hold locks across await points without heartbeat
async with lock:
await slow_external_api() # Lock may expire!Related Skills
idempotency-patterns- Complement locks with idempotencycaching-strategies- Redis patternsbackground-jobs- Job deduplication
References
- Redis Locks - Lua scripts, retry, extend
- Redlock Algorithm - Multi-node HA
- PostgreSQL Advisory - Session/transaction
Capability Details
redis-locks
Keywords: Redis, Lua, SET NX, atomic, TTL Solves: Fast distributed locks, atomic acquire/release, auto-expiry
redlock
Keywords: Redlock, multi-node, quorum, HA, fault-tolerant Solves: High-availability locking, survive node failures
advisory-locks
Keywords: PostgreSQL, advisory, pg_advisory_lock, session, transaction Solves: Lock with existing PG, ACID integration, no extra infra
leader-election
Keywords: leader, election, singleton, coordinator Solves: Single active instance, coordinator pattern