Agent skill
distributed-locks
Distributed locking patterns with Redis and PostgreSQL for coordination across instances. Use when implementing exclusive access, preventing race conditions, or coordinating distributed resources.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/distributed-locks
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?