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 idempotency
• caching-strategies - Redis patterns
• background-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