How to Write Lua Script for Redis: Simple Guide with Examples

Write Lua scripts for Redis by using the EVAL command with your Lua code as a string and specifying the number of keys followed by key names and arguments, like EVAL 'return redis.call("GET", KEYS[1])' 1 mykey.

Examples

InputEVAL 'return redis.call("GET", KEYS[1])' 1 mykey

Outputvalue_of_mykey

InputEVAL 'redis.call("SET", KEYS[1], ARGV[1]); return redis.call("GET", KEYS[1])' 1 mykey newvalue

Outputnewvalue

InputEVAL 'return tonumber(ARGV[1]) + tonumber(ARGV[2])' 0 5 7

Output12

How to Think About It

To write a Lua script for Redis, think about what Redis commands you want to run atomically. Use redis.call inside Lua to run Redis commands. Pass keys as KEYS array and extra arguments as ARGV array. Then run the script with EVAL specifying how many keys you use.

Algorithm

1

Write Lua code using <code>redis.call</code> to execute Redis commands.

2

Use <code>KEYS</code> array to access keys and <code>ARGV</code> array for extra arguments.

3

Run the script with <code>EVAL</code> command, passing the Lua code as a string.

4

Specify the number of keys and list the keys after the count.

5

Add any additional arguments after the keys.

6

The script runs atomically and returns the result.

Code

redis

EVAL 'redis.call("SET", KEYS[1], ARGV[1]); return redis.call("GET", KEYS[1])' 1 mykey hello

Output

hello

Dry Run

Let's trace the script that sets and gets a key 'mykey' with value 'hello'.

1

Set key

redis.call("SET", KEYS[1], ARGV[1]) sets 'mykey' to 'hello'

2

Get key

redis.call("GET", KEYS[1]) returns 'hello'

Step	Operation	Key	Value
1	SET	mykey	hello
2	GET	mykey	hello

Why This Works

Step 1: Using redis.call

The redis.call function runs Redis commands inside Lua scripts.

Step 2: Passing keys and arguments

KEYS holds keys, ARGV holds extra arguments passed to the script.

Step 3: Atomic execution

The entire Lua script runs atomically, so commands inside it execute without interruption.

Alternative Approaches

Using redis.pcall for error handling

redis

EVAL 'local res = redis.pcall("GET", KEYS[1]); if res.err then return "Error" else return res end' 1 mykey

This method catches errors without stopping the script, useful for safer scripts.

Using Lua script files with Redis SCRIPT LOAD

redis

SCRIPT LOAD 'return redis.call("GET", KEYS[1])' then EVALSHA <sha> 1 mykey

Load scripts once and run by SHA for better performance on repeated calls.

Complexity: O(1) to O(n) time, O(1) space

Time Complexity

Lua scripts run Redis commands sequentially; complexity depends on commands used, often O(1) for simple gets/sets.

Space Complexity

Scripts use constant extra space; data stored in Redis is not duplicated.

Which Approach is Fastest?

Using EVALSHA after loading scripts is faster than EVAL because it avoids parsing the script each time.

Approach	Time	Space	Best For
EVAL	O(n) depending on commands	O(1)	Simple or one-time scripts
EVALSHA with SCRIPT LOAD	Faster after load	O(1)	Repeated script execution
redis.pcall error handling	Slightly slower	O(1)	Safe scripts with error catching