Lua scripting in Tair (Redis OSS-compatible)

Lua commands

Full command documentation is available on the Redis official website.

SET foo value_test

EVAL "return redis.call('GET', KEYS[1])" 1 foo

"value_test"

SCRIPT LOAD "return redis.call('GET', KEYS[1])"

"620cd258c2c9c88c9d10db67812ccf663d96bdc6"

EVALSHA 620cd258c2c9c88c9d10db67812ccf663d96bdc6 1 foo

"value_test"

SCRIPT EXISTS 620cd258c2c9c88c9d10db67812ccf663d96bdc6 ffffffffffffffffffffffffffffffffffffffff

1) (integer) 1
2) (integer) 0

SCRIPT FLUSH

OK

Reduce memory and network overhead

When multiple scripts with duplicate logic are cached separately, they waste memory and can cause an OOM error.

Problem -- hardcoded constants create separate cache entries:

EVAL "return redis.call('set', 'k1', 'v1')" 0
EVAL "return redis.call('set', 'k2', 'v2')" 0

Solution 1 -- use KEYS and ARGV so the same script is cached once:

EVAL "return redis.call('set', KEYS[1], ARGV[1])" 1 k1 v1
EVAL "return redis.call('set', KEYS[1], ARGV[1])" 1 k2 v2

Solution 2 -- cache the script once with SCRIPT LOAD, then call it with EVALSHA:

SCRIPT LOAD "return redis.call('set', KEYS[1], ARGV[1])"
# Returns: "55b22c0d0cedf3866879ce7c854970626dcef0c3"

EVALSHA 55b22c0d0cedf3866879ce7c854970626dcef0c3 1 k1 v1
EVALSHA 55b22c0d0cedf3866879ce7c854970626dcef0c3 1 k2 v2

Manage the Lua script cache

The Lua script cache consumes instance memory. When used memory approaches or exceeds the limit, the instance returns an OOM error:

-OOM command not allowed when used memory > 'maxmemory'.

To flush the cache, run SCRIPT FLUSH on the client.

Avoid Lua scripts that consume excessive memory or process large datasets. Manage cache growth with data eviction policies.

Handle NOSCRIPT errors

When EVALSHA targets a script that is not in the cache, the instance returns:

(error) NOSCRIPT No matching script. Please use EVAL.

Cause: The script was never loaded, or the cache was cleared during a migration, configuration change, version upgrade, or switchover. Tair does not guarantee persistence or replication of cached scripts across these events.

Solution: Run EVAL or SCRIPT LOAD to re-cache the script. Your client should handle the NOSCRIPT error gracefully.

The redis-py library provides a Script class that handles NOSCRIPT errors automatically.

The following Python example shows manual NOSCRIPT handling. The script prepends a string to an existing key value:

import redis
import hashlib

# Returns the SHA1 hex digest of a string.
def calcSha1(strin):
    sha1_obj = hashlib.sha1()
    sha1_obj.update(strin.encode('utf-8'))
    sha1_val = sha1_obj.hexdigest()
    return sha1_val

class MyRedis(redis.Redis):

    def __init__(self, host="localhost", port=6379, password=None, decode_responses=False):
        redis.Redis.__init__(self, host=host, port=port, password=password, decode_responses=decode_responses)

    def prepend_inLua(self, key, value):
        script_content = """\
        local suffix = redis.call("get", KEYS[1])
        local prefix = ARGV[1]
        local new_value = prefix..suffix
        return redis.call("set", KEYS[1], new_value)
        """
        script_sha1 = calcSha1(script_content)
        if self.script_exists(script_sha1)[0] == True:      # Check whether the script is already cached.
            return self.evalsha(script_sha1, 1, key, value) # If cached, use EVALSHA.
        else:
            return self.eval(script_content, 1, key, value) # Otherwise, use EVAL (which also caches the script).

r = MyRedis(host="r-******.redis.rds.aliyuncs.com", password="***:***", port=6379, decode_responses=True)

print(r.prepend_inLua("k", "v"))
print(r.get("k"))

Handle Lua script timeouts (BUSY error)

Lua scripts run atomically. A slow script blocks the entire instance. After 5 seconds of blocking, the instance returns a BUSY error for all other commands:

BUSY Redis is busy running a script. You can only call SCRIPT KILL or SHUTDOWN NOSAVE.

Solution: Run SCRIPT KILL to terminate the script, or wait for it to finish.

SCRIPT KILL does not take effect during the first 5 seconds of script execution because the instance is blocked.

To prevent extended blocking, estimate execution time before deploying a script, check for infinite loops, and split large scripts if necessary.

Handle UNKILLABLE errors

If a Lua script has already run write commands, SCRIPT KILL fails:

(error) UNKILLABLE Sorry the script already executed write commands against the dataset. You can either wait the script termination or kill the server in a hard way using the SHUTDOWN NOSAVE command.

Solution: On the Instances page of the console, find the target instance and click restart.

Script persistence and replication

Tair keeps Lua scripts cached unless the instance restarts or SCRIPT FLUSH is run. Script persistence and cross-node synchronization are not guaranteed during:

• Instance migrations

• Configuration changes

• Version upgrades

• Instance switchovers

Solution: Store all Lua scripts locally. Re-cache them with EVAL or SCRIPT LOAD after any restart or HA switchover to prevent NOSCRIPT errors.

Cluster instance constraints

# Valid
EVAL "return redis.call('get', KEYS[1])" 1 fooeval

# Invalid -- no key specified
EVAL "return redis.call('get', 'foo')" 0

# Valid -- {foo} hash tag ensures same slot
EVAL "return redis.call('mget', KEYS[1], KEYS[2])" 2 foo {foo}bar

# Invalid -- foo and foobar may hash to different slots
EVAL "return redis.call('mget', KEYS[1], KEYS[2])" 2 foo foobar

# Valid
EVAL "local value = redis.call('GET', KEYS[1]); redis.call('SET', KEYS[2], value)" 2 foo bar

# Invalid -- nested call
EVAL "redis.call('SET', KEYS[1], redis.call('GET', KEYS[2]))" 2 foo bar

# Valid
eval "redis.call('GET', KEYS[1])" 1 foo

# Invalid -- command name stored in a variable
eval "local cmd = 'GET'; redis.call(cmd, KEYS[1])" 1 foo

# Valid
EVAL "return redis.call('mget', KEYS[1], KEYS[2])" 2 foo {foo}bar

# Invalid -- key as string literal
EVAL "return redis.call('mget', KEYS[1], '{foo}bar')" 1 foo

# Invalid -- variable index for KEYS (not allowed in proxy mode; allowed in direct connection mode)
EVAL "local i = 2 return redis.call('mget', KEYS[1], KEYS[i])" 2 foo {foo}bar

# Invalid -- ARGV used as a key
EVAL "return redis.call('mget', KEYS[1], ARGV[1])" 1 foo {foo}bar

FAQ

Does Data Management Service (DMS) support Lua scripts?

No. DMS does not support Lua commands. Use a Redis client or redis-cli instead.