PolarDB:Lua script usage guide

Comandos no admitidos

A continuación se muestran los comandos que no se pueden invocar dentro de un script de Lua mediante redis.call() ni redis.pcall():

• Control de transacciones: WATCH, UNWATCH, MULTI, EXEC, DISCARD

• Comandos de bloqueo: BLPOP, BRPOP

• Comandos de scripting de Lua: EVAL, EVAL_RO, EVALSHA, EVALSHA_RO, SCRIPT

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

• Gestión de conexiones: AUTH, HELLO, CLIENT

Si invoca cualquiera de estos comandos, se devolverá un error de inmediato.

Implementar un contador atómico

Utilice scripts de Lua para evitar las condiciones de carrera que generan las operaciones INCR simultáneas. El patrón SCRIPT LOAD + EVALSHA evita transmitir el contenido del script en las llamadas posteriores. De este modo, se reduce el tráfico de red y mejora el rendimiento.

1. Escriba el script y guárdelo de forma local:

-- 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. Cargue el script para obtener su suma de comprobación SHA1:

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

Salida:

"b547eabbcde73b25330442e4f4e4dc1783b91241"

3. Ejecute el script mediante su suma de comprobación SHA1:

EVALSHA b547eabbcde73b25330442e4f4e4dc1783b91241 1 my_counter

Salida en la primera llamada:

(integer) 1

Salida en la segunda llamada:

(integer) 2

Ejecutar un script de solo lectura

Use EVAL_RO o EVALSHA_RO para garantizar que un script no ejecute operaciones de escritura. Esta opción resulta útil en escenarios de división de lectura y escritura donde los scripts solo deben acceder a las réplicas de lectura.

Antes de usar EVAL_RO, confirme que su script no invoque comandos de escritura como SET, DEL, HSET o LPUSH. Si los incluye, use EVAL en su lugar.

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

Salida:

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

Detener un script de ejecución prolongada

Si un script tarda más de lo esperado y bloquea el clúster, finalícelo con SCRIPT KILL. Orca revierte automáticamente todos los cambios que haya hecho el script.

SCRIPT KILL

Salida:

OK

Usar SCRIPT LOAD + EVALSHA en cargas de trabajo de producción

Todos los ejemplos siguientes usan SCRIPT LOAD durante el inicio para almacenar los scripts en la caché y luego emplean EVALSHA en cada llamada posterior. Este patrón evita retransmitir el script completo en cada solicitud.

1. Cargue el script durante la inicialización de la aplicación:

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

Salida:

"55b22c0d0cedf3866879ce7c854970626dcef0c3"

Almacene este valor SHA1 en su aplicación.

2. Ejecute el script mediante el SHA1 almacenado en la caché:

# Set k1 = v1
EVALSHA 55b22c0d0cedf3866879ce7c854970626dcef0c3 1 k1 v1

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

3. Gestione los errores NOSCRIPT:

Si EVALSHA devuelve un error NOSCRIPT, significa que el script ya no está en la caché. Cambie a EVAL o SCRIPT LOAD para volver a ejecutar el script y almacenarlo de nuevo en la caché. Después, retome el uso de EVALSHA.

Parametrizar scripts con KEYS[] y ARGV[]

Pase todos los datos variables mediante KEYS[] y ARGV[] en lugar de codificar valores de forma fija en el cuerpo del script. Los scripts con valores fijos son cadenas únicas, por lo que cada variante genera una entrada de caché independiente. Esto aumenta el consumo de memoria y anula las ventajas de la caché.

El siguiente ejemplo muestra el antipatrón y el enfoque correcto:

-- 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!

Mantener los scripts cortos y rápidos

Los scripts de Lua se ejecutan de forma atómica y bloquean todos los demás comandos durante su ejecución. Los scripts de ejecución prolongada o con lotes grandes aumentan la latencia del clúster para el resto de los clientes.

• Evite bucles complejos o recorridos de datos a gran escala dentro de los scripts.

• El tiempo de espera de ejecución predeterminado es de 300 segundos. Si un script supera este límite, simplifique la lógica.

• Divida las operaciones complejas en varios scripts pequeños en lugar de usar uno solo de gran tamaño.

Borrar la caché de scripts de forma segura

Use SCRIPT FLUSH para eliminar todos los scripts almacenados en la caché. Después de borrarla, cualquier llamada a EVALSHA o EVALSHA_RO devolverá un error NOSCRIPT hasta que se vuelvan a cargar los scripts.

SCRIPT FLUSH

Salida:

OK

Conserve el código fuente de los scripts en su aplicación e implemente una recuperación automática para los errores NOSCRIPT. Cuando ocurra un error, vuelva a cargar el script con SCRIPT LOAD o regístrelo de nuevo con EVAL.