Lua脚本使用规范

注意事项

数据管理服务DMS控制台目前暂不支持使用Lua脚本等相关命令，请通过客户端或Redis-cli连接Tair实例使用Lua脚本。

基本语法

更多关于Redis命令的介绍，请参见Redis Commands。

优化内存、网络开销

现象：

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

清理Lua脚本的内存占用

现象：

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

解决方案：

同时，请避免编写过大的Lua脚本，防止占用过多的内存；避免在Lua脚本中大批量写入数据，否则会导致内存使用急剧升高，甚至造成实例OOM。在业务允许的情况下，建议开启数据逐出（Tair默认开启，模式为volatile-lru）节省内存空间。但无论是否开启数据逐出，Tair均不会逐出Lua脚本缓存。

处理NOSCRIPT错误

现象：

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

解决方案：

请通过EVAL命令或SCRIPT LOAD命令将目标脚本缓存至Tair中后进行重试。但由于Tair不保证Lua脚本的持久化、复制能力，Tair在部分场景下仍会清除Lua脚本缓存（例如实例迁移、变配等），这要求您的客户端需具备处理该错误的能力，详情请参见脚本缓存、持久化与复制。

import redis
import hashlib

# strin是一个Lua脚本的字符串，函数以字符串的格式返回strin的sha1值。
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:      # 检查Tair是否已缓存该脚本。
            return self.evalsha(script_sha1, 1, key, value) # 如果已缓存，则用EVALSHA执行脚本
        else:
            return self.eval(script_content, 1, key, value) # 否则用EVAL执行脚本，注意EVAL有将脚本缓存到Tair的作用。这里也可以考虑采用SCRIPT LOAD与EVALSHA的方式。

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

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

处理Lua脚本超时

• 现象：

  由于Lua脚本在Tair中是原子执行的，Lua慢请求可能会导致Tair阻塞。单个Lua脚本阻塞Tair最多5秒，5秒后Tair会给所有其他命令返回如下BUSY error报错，直到脚本执行结束。

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

  解决方案：

  您可以通过SCRIPT KILL命令终止Lua脚本或等待Lua脚本执行结束。
  说明

  • SCRIPT KILL命令在执行慢Lua脚本的前5秒不会生效（Tair阻塞中）。
  • 建议您编写Lua脚本时预估脚本的执行时间，同时检查死循环等问题，避免过长时间阻塞Tair导致服务不可用，必要时请拆分Lua脚本。

• 现象：

  若当前Lua脚本已执行写命令，则SCRIPT KILL命令将无法生效，报错示例如下。

  (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.

  解决方案：

  请在控制台的实例列表中单击对应实例重启。

脚本缓存、持久化与复制

现象：

在不重启、不调用SCRIPT FLUSH命令的情况下，Tair会一直缓存执行过的Lua脚本。但在部分情况下（例如实例迁移、变配、版本升级、切换等等），Tair无法保证Lua脚本的持久化，也无法保证Lua脚本能够被同步至其他节点。

解决方案：

由于Tair不保证Lua脚本的持久化、复制能力，请您在本地存储所有Lua脚本，在必要时通过EVAL或SCRIPT LOAD命令将Lua脚本重新缓存至Tair中，避免实例重启、HA切换等操作时Tair中Lua脚本被清空而带来的NOSCRIPT错误。

集群中Lua脚本的限制

Redis Cluster对使用Lua脚本增加了一些限制，在此基础上，Tair集群版对使用Lua脚本存在如下额外限制：

• 小版本限制，若无法执行EVAL的相关命令，并报错ERR command eval not support for normal user时，请升级小版本后重试，具体操作请参见升级小版本。
• 所有Key必须在一个slot上，否则报错-ERR eval/evalsha command keys must be in same slot\r\n。

  您可以通过CLUSTER KEYSLOT命令获取目标Key的哈希槽（Hash Slot）进行确认。

• 对单个节点执行SCRIPT LOAD命令时，不保证将该Lua脚本存入至其他节点中。
• 不支持发布订阅命令，包括PSUBSCRIBE、PUBSUB、PUBLISH、PUNSUBSCRIBE、SUBSCRIBE和UNSUBSCRIBE。
• 不支持UNPACK函数。

代理模式（Proxy）执行Lua的额外限制

• 所有key都应该由KEYS数组来传递，redis.call/pcall中调用的Tair命令，key的位置必须是KEYS array，且不能使用Lua变量替换KEYS，否则直接返回错误信息：

  -ERR bad lua script for redis cluster, all the keys that the script uses should be passed using the KEYS array\r\n

  正确与错误命令示例如下：

  # 本示例的准备工作需执行如下命令。
  SET foo foo_value
  SET {foo}bar bar_value
  
  # 正确示例：
  EVAL "return redis.call('mget', KEYS[1], KEYS[2])" 2 foo {foo}bar
  
  # 错误示例：
  EVAL "return redis.call('mget', KEYS[1], '{foo}bar')" 1 foo                      # '{foo}bar'作为Key，应该使用KEYS数组进行传递。
  EVAL "local i = 2 return redis.call('mget', KEYS[1], KEYS[i])" 2 foo {foo}bar    # 在代理模式（Proxy）不允许执行此脚本，因为KEYS数据的索引是变量，但在直连模式中无此限制。
  EVAL "return redis.call('mget', KEYS[1], ARGV[1])" 1 foo {foo}bar                # 不应该使用ARGV[1]数据元素作为Key。

• 调用必须要带有key，否则直接返回错误信息：

  -ERR for redis cluster, eval/evalsha number of keys can't be negative or zero\r\n

  正确与错误命令示例如下：

  # 正确示例
  EVAL "return redis.call('get', KEYS[1])" 1 foo
  
  # 错误示例
  EVAL "return redis.call('get', 'foo')" 0

• 不支持在MULTI、EXEC事务中使用EVAL、EVALSHA、SCRIPT系列命令。
• 不支持在Lua中执行跨Tair节点的命令，例如KEYS、SCAN等。

  为了保证Lua执行的原子性，Proxy会根据KEYS参数将Lua发送到一个Tair节点执行并获取结果，从而导致该结果与全局结果不一致。