PolarDB:Lua script usage guide

Unsupported commands

The following commands cannot be called inside a Lua script using redis.call() or redis.pcall():

• Transaction control: WATCH, UNWATCH, MULTI, EXEC, DISCARD

• Blocking commands: BLPOP, BRPOP

• Lua scripting commands: EVAL, EVAL_RO, EVALSHA, EVALSHA_RO, SCRIPT

• Pub/Sub commands: SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE

• Connection management: AUTH, HELLO, CLIENT

Calling any of these returns an error immediately.

Implement an atomic counter

Use Lua scripting to avoid race conditions from concurrent INCR operations. The SCRIPT LOAD + EVALSHA pattern keeps the script content off the wire for subsequent calls, reducing network traffic and improving throughput.

1. Write the script and save it locally:

-- counter.lua
-- Initialize the key to 0 if it does not exist, then increment by 1.
if redis.call('EXISTS', KEYS[1]) == 0 then
  redis.call('SET', KEYS[1], 0)
end
return redis.call('INCR', KEYS[1])

2. Load the script to get its SHA1 checksum:

SCRIPT LOAD "if redis.call('EXISTS', KEYS[1]) == 0 then redis.call('SET', KEYS[1], 0) end return redis.call('INCR', KEYS[1])"

Output:

"b547eabbcde73b25330442e4f4e4dc1783b91241"

3. Execute the script using its SHA1 checksum:

EVALSHA b547eabbcde73b25330442e4f4e4dc1783b91241 1 my_counter

Output on first call:

(integer) 1

Output on second call:

(integer) 2

Run a read-only script

Use EVAL_RO or EVALSHA_RO to guarantee that a script does not perform write operations. This is useful for read/write splitting scenarios where scripts must only touch read replicas.

Before using EVAL_RO, confirm your script calls no write commands such as SET, DEL, HSET, or LPUSH. If it does, use EVAL instead.

EVAL_RO "return {redis.call('GET', KEYS[1]), redis.call('TTL', KEYS[1])}" 1 polardb

Output:

1) "orca"
2) (integer) -1

Stop a long-running script

If a script runs longer than expected and blocks the cluster, terminate it with SCRIPT KILL. Orca automatically rolls back all changes the script has made.

SCRIPT KILL

Output:

OK

Use SCRIPT LOAD + EVALSHA for production workloads

All examples below use SCRIPT LOAD at startup to cache scripts, then EVALSHA for every subsequent call. This pattern avoids retransmitting the full script on each request.

1. Load the script during application initialization:

# Cache a script that sets a key's value
SCRIPT LOAD "return redis.call('set', KEYS[1], ARGV[1])"

Output:

"55b22c0d0cedf3866879ce7c854970626dcef0c3"

Store this SHA1 value in your application.

2. Execute the script using the cached SHA1:

# Set k1 = v1
EVALSHA 55b22c0d0cedf3866879ce7c854970626dcef0c3 1 k1 v1

# Set k2 = v2 using the same cached script
EVALSHA 55b22c0d0cedf3866879ce7c854970626dcef0c3 1 k2 v2

3. Handle `NOSCRIPT` errors:

If EVALSHA returns a NOSCRIPT error, the script is no longer in the cache. Switch to EVAL or SCRIPT LOAD to re-execute and re-cache the script, then resume using EVALSHA.

Parameterize scripts with KEYS[] and ARGV[]

Pass all variable data through KEYS[] and ARGV[] instead of hard-coding values in the script body. Hard-coded scripts are unique strings—each variation generates a separate cache entry, which inflates memory usage and defeats caching.

The following example shows the anti-pattern and the correct approach:

-- Anti-pattern: each hard-coded variant creates a separate cache entry
EVAL "return 'Hello'" 0
EVAL "return 'Scripting!'" 0

-- Correct: one parameterized script reuses the same cache entry for any value
EVAL "return ARGV[1]" 0 Hello
EVAL "return ARGV[1]" 0 Scripting!

Keep scripts short and fast

Lua scripts execute atomically and block all other commands during execution. Long-running or large-batch scripts increase cluster latency for every other client.

• Avoid complex loops or large-scale data traversals inside scripts.

• The default execution timeout is 300 seconds. A script that exceeds this limit is a signal to simplify the logic.

• Split complex operations into multiple smaller scripts instead of one large one.

Clear the script cache safely

Use SCRIPT FLUSH to remove all cached scripts. After flushing, any call to EVALSHA or EVALSHA_RO returns a NOSCRIPT error until scripts are reloaded.

SCRIPT FLUSH

Output:

OK

Keep script source code in your application and implement automatic recovery for NOSCRIPT errors. On error, reload the script with SCRIPT LOAD or re-register it with EVAL.