A-2 — Lua Scripting: EVAL, EVALSHA, and Atomic Compound Operations

Script cache persistence: The script cache lives in Redis memory and is cleared on restart. Your application must re-load scripts after a Redis restart. Pattern:

async function callScript(sha: string, script: string, ...args: Parameters<typeof redis.evalsha>) {
  try {
    return await redis.evalsha(sha, ...args);
  } catch (err: any) {
    if (err.message.includes('NOSCRIPT')) {
      // Script was flushed — reload and retry
      await redis.script('LOAD', script);
      return await redis.evalsha(sha, ...args);
    }
    throw err;
  }
}

SCRIPT EXISTS sha1 [sha1 ...] — check if scripts are loaded:

SCRIPT EXISTS 2067d915024a3e1657c4169c84f809f8ec75b9a7
→ 1) (integer) 1   ← loaded
   2) (integer) 0   ← not loaded

SCRIPT FLUSH — clear all cached scripts. Run this after code changes that modify Lua scripts.

---

Production Lua Patterns

Pattern 1: Atomic Rate Limiter

The sliding window rate limiter with Sorted Sets (from P-5) requires multiple commands. In a pipeline, they are not atomic. In Lua, they are:

-- KEYS[1] = rate limit key
-- ARGV[1] = window duration in ms
-- ARGV[2] = max requests in window
-- ARGV[3] = current timestamp in ms
 
local key = KEYS[1]
local window = tonumber(ARGV[1])
local limit = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local window_start = now - window
 
-- Remove expired entries
redis.call('ZREMRANGEBYSCORE', key, 0, window_start)
 
-- Count current entries
local count = redis.call('ZCARD', key)
 
if count >= limit then
  -- Reject: return 0 + time until next slot opens
  local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
  local retry_after = oldest[2] and (tonumber(oldest[2]) + window - now) or 0
  return {0, math.ceil(retry_after)}
end
 
-- Allow: add this request
redis.call('ZADD', key, now, now .. '-' .. math.random(1000000))
redis.call('PEXPIRE', key, window)
return {1, limit - count - 1}  -- {allowed, remaining}

const rateLimiterSha = await redis.script('LOAD', rateLimiterScript);
 
async function checkRateLimit(userId: string): Promise<{ allowed: boolean; remaining: number; retryAfter?: number }> {
  const result = await redis.evalsha(
    rateLimiterSha, 1,
    `rate:${userId}`,
    '60000',  // 60-second window
    '100',    // 100 requests per window
    String(Date.now())
  ) as [number, number];
 
  return {
    allowed: result[0] === 1,
    remaining: result[1],
    retryAfter: result[0] === 0 ? result[1] : undefined,
  };
}

Pattern 2: Conditional Set (Set If Less Than)

Update a leaderboard score only if it is higher than the current score — atomically:

-- KEYS[1] = sorted set key
-- ARGV[1] = member
-- ARGV[2] = new score
 
local current = redis.call('ZSCORE', KEYS[1], ARGV[1])
if current == false or tonumber(ARGV[2]) > tonumber(current) then
  redis.call('ZADD', KEYS[1], ARGV[2], ARGV[1])
  return 1  -- updated
end
return 0  -- not updated (current score is higher)

Without Lua, this would require WATCH + MULTI/EXEC with a retry loop. With Lua: one atomic call.

Pattern 3: Atomic Inventory Deduction

-- KEYS[1] = inventory key
-- ARGV[1] = quantity to deduct
 
local current = tonumber(redis.call('GET', KEYS[1]))
if current == nil then
  return {-1, 0}  -- item doesn't exist
end
if current < tonumber(ARGV[1]) then
  return {0, current}  -- insufficient inventory
end
local remaining = current - tonumber(ARGV[1])
redis.call('SET', KEYS[1], remaining)
return {1, remaining}  -- success, remaining quantity

Pattern 4: Get-or-Set (Single-Flight Cache)

-- KEYS[1] = cache key
-- ARGV[1] = lock key
-- ARGV[2] = lock value (UUID)
-- ARGV[3] = lock TTL in ms
 
local cached = redis.call('GET', KEYS[1])
if cached then
  return {1, cached}  -- cache hit
end
 
-- Try to acquire lock for recompute
local locked = redis.call('SET', ARGV[1], ARGV[2], 'NX', 'PX', ARGV[3])
if locked then
  return {2, nil}  -- acquired lock — caller should recompute and populate
else
  return {0, nil}  -- lock held by another — caller should wait and retry
end

---

Debugging Lua Scripts

redis.log

redis.log(redis.LOG_WARNING, "Script executing with key: " .. KEYS[1])
redis.log(redis.LOG_VERBOSE, "Current value: " .. tostring(current))

Log levels: LOG_DEBUG, LOG_VERBOSE, LOG_NOTICE, LOG_WARNING. Output appears in the Redis log file.

SCRIPT DEBUG

Redis 3.2+ includes a Lua debugger. Start a debugging session:

redis-cli --ldb -e 'return redis.call("GET", KEYS[1])' 1 mykey

Commands in debug mode: s (step), n (next), c (continue), b line (breakpoint), p var (print), l (list source).

Test Scripts in Isolation

Before deploying a Lua script, test it with EVAL directly in redis-cli with representative inputs. Verify the return values match your expected Redis response types.

---

Execution Limits

lua-time-limit 5000 → script cannot run for more than 5 seconds (default)

After lua-time-limit milliseconds, Redis stops accepting most new commands and returns a BUSY error. The script cannot be killed immediately — you can send SCRIPT KILL to terminate a script that has not yet performed any writes. If the script has written data, SCRIPT KILL is refused (to prevent partial writes), and only SHUTDOWN NOSAVE will stop Redis.

This is why Lua scripts must be fast. A script that loops over a large dataset or has an infinite loop can make Redis completely unresponsive.

Design rule: Lua scripts should complete in microseconds to single-digit milliseconds. If you need to process large datasets, do it in application code with SCAN-based iteration — not in a single Lua script.

---

Summary

• Lua scripts execute atomically on the Redis server — no other command runs during script execution
• EVAL script numkeys KEYS... ARGV... — pass key names via KEYS (required for Cluster routing), other params via ARGV
• redis.call() aborts on error; redis.pcall() catches and returns errors as Lua tables
• SCRIPT LOAD uploads a script and returns its SHA1; EVALSHA calls by SHA (avoids retransmitting the script body on every call)
• Handle NOSCRIPT errors after Redis restart by reloading scripts automatically
• Lua enables atomic operations impossible with MULTI/EXEC: read-then-decide-then-write, conditional updates, get-or-set
• Scripts must be fast — lua-time-limit (default 5s) blocks all clients when exceeded; design for < 1ms execution
• Debug with redis.log() and redis-cli --ldb

Next: A-3 — Redis Functions: Persistent Stored Procedures — how Redis Functions differ from Lua scripts (functions survive restarts), function libraries, and when to migrate from EVALSHA to Functions.

---