Transactions, Lua scripting and atomicity

MULTI and EXEC, WATCH for optimistic locking, EVAL with correct KEYS usage, Redis Functions, and the patterns that need real atomicity.

MULTI, EXEC and WATCH

MULTI
INCR balance:42
DECR balance:7
EXEC

# optimistic locking: abort if the watched key changed
WATCH inventory:sku1
val = GET inventory:sku1
MULTI
DECRBY inventory:sku1 3
EXEC          # returns nil if anything watched changed since WATCH

# be honest about what MULTI gives you
MULTI
SET a 1
LPUSH a 2      # wrong type: not reported here
EXEC           # error reported here, but other commands still ran

• MULTI queues commands and EXEC runs them without interruption, but there is no rollback: if one command fails at runtime the others still take effect.
• Syntax errors are detected at queue time and abort the whole transaction; runtime errors such as WRONGTYPE do not.
• WATCH is compare-and-set: it fails the transaction if a watched key changed. Your client must retry the whole read-modify-write loop on a nil reply.
• A transaction cannot read a value and branch on it - the commands are queued, not executed. That is exactly the gap Lua fills.

Lua scripting

-- rate limit: increment and set a TTL only on the first hit
-- KEYS[1] = counter key, ARGV[1] = limit, ARGV[2] = window seconds
local current = redis.call('INCR', KEYS[1])
if current == 1 then
  redis.call('EXPIRE', KEYS[1], ARGV[2])
end
if current > tonumber(ARGV[1]) then
  return 0
end
return 1

redis-cli --eval ratelimit.lua counter:user:42 , 100 60

# or inline
EVAL "return redis.call('GET', KEYS[1])" 1 mykey

# load once, run by hash: the preferred production pattern
SCRIPT LOAD "return redis.call('GET', KEYS[1])"
EVALSHA <sha1> 1 mykey
SCRIPT EXISTS <sha1>

• A script is atomic: nothing else runs between its commands. That is the real reason to use one, not performance alone.
• Passing a key in ARGV instead of KEYS works in a standalone instance and breaks immediately in cluster mode.
• EVALSHA avoids resending the body; on NOSCRIPT your client must fall back to SCRIPT LOAD and retry.
• Scripts are cached by SHA and are not part of persistence. After a restart the cache is empty, so a robust client always handles NOSCRIPT.

Redis Functions and atomic patterns

#!lua name=mylib

redis.register_function('claim_job', function(keys, args)
  local job_id = redis.call('LMOVE', keys[1], keys[2], 'LEFT', 'RIGHT')
  if not job_id then return false end
  redis.call('HSET', keys[3], job_id, args[1])
  return job_id
end)

FUNCTION LOAD "#!lua name=mylib\n..."
FCALL claim_job 3 queue:pending queue:processing jobs:leases worker-1
FUNCTION LIST
FUNCTION STATS

-- release a lock only if you still own it: the classic compare-and-delete
-- KEYS[1] = lock key, ARGV[1] = my token
if redis.call('GET', KEYS[1]) == ARGV[1] then
  return redis.call('DEL', KEYS[1])
end
return 0

Any read-then-write sequence issued as two round trips is a race. If the correctness of your feature depends on the pair being atomic, it must be a script or a function - the network is not part of your transaction.

FAQ

Related

Distributed locks and rate limiting Data types and the commands that matter

Last refreshed 2026-09-18.