PolarDB:Lua script usage guide

Comandos não suportados

Os seguintes comandos não podem ser chamados dentro de um script Lua usando redis.call() ou redis.pcall():

• Controle de transações: WATCH, UNWATCH, MULTI, EXEC, DISCARD

• Comandos de bloqueio: BLPOP, BRPOP

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

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

• Gerenciamento de conexões: AUTH, HELLO, CLIENT

Chamar qualquer um desses comandos retorna um erro imediatamente.

Implementar um contador atômico

Use scripts Lua para evitar condições de corrida causadas por operações INCR simultâneas. O padrão SCRIPT LOAD + EVALSHA evita o envio do conteúdo do script pela rede nas chamadas subsequentes, reduzindo o tráfego e melhorando o throughput.

1. Escreva o script e salve-o localmente:

-- 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. Carregue o script para obter sua soma de verificação SHA1:

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

Saída:

"b547eabbcde73b25330442e4f4e4dc1783b91241"

3. Execute o script usando sua soma de verificação SHA1:

EVALSHA b547eabbcde73b25330442e4f4e4dc1783b91241 1 my_counter

Saída na primeira chamada:

(integer) 1

Saída na segunda chamada:

(integer) 2

Executar um script somente leitura

Use EVAL_RO ou EVALSHA_RO para garantir que um script não realize operações de escrita. Isso é útil em cenários de divisão de leitura e escrita, onde os scripts devem acessar apenas réplicas de leitura.

Antes de usar EVAL_RO, confirme se o seu script não chama comandos de escrita como SET, DEL, HSET ou LPUSH. Caso contrário, use EVAL.

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

Saída:

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

Interromper um script de longa duração

Se um script demorar mais do que o esperado e bloquear o cluster, encerre-o com SCRIPT KILL. O Orca reverte automaticamente todas as alterações feitas pelo script.

SCRIPT KILL

Saída:

OK

Usar SCRIPT LOAD + EVALSHA para cargas de trabalho de produção

Todos os exemplos abaixo usam SCRIPT LOAD na inicialização para armazenar scripts em cache e, em seguida, EVALSHA para cada chamada subsequente. Esse padrão evita a retransmissão do script completo a cada solicitação.

1. Carregue o script durante a inicialização da aplicação:

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

Saída:

"55b22c0d0cedf3866879ce7c854970626dcef0c3"

Armazene esse valor SHA1 em sua aplicação.

2. Execute o script usando o SHA1 em cache:

# Set k1 = v1
EVALSHA 55b22c0d0cedf3866879ce7c854970626dcef0c3 1 k1 v1

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

3. Trate erros NOSCRIPT:

Se EVALSHA retornar um erro NOSCRIPT, significa que o script não está mais no cache. Mude para EVAL ou SCRIPT LOAD para executar e armazenar o script novamente no cache e, depois, retome o uso de EVALSHA.

Parametrizar scripts com KEYS[] e ARGV[]

Passe todos os dados variáveis por meio de KEYS[] e ARGV[] em vez de codificar valores fixos no corpo do script. Scripts com valores fixos são strings únicas — cada variação gera uma entrada de cache separada, o que aumenta o uso de memória e anula os benefícios do cache.

O exemplo a seguir mostra o antipadrão e a abordagem correta:

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

Manter scripts curtos e rápidos

Scripts Lua são executados atomicamente e bloqueiam todos os outros comandos durante a execução. Scripts de longa duração ou com grandes lotes de processamento aumentam a latência do cluster para todos os outros clientes.

• Evite loops complexos ou travessias de dados em grande escala dentro dos scripts.

• O tempo limite padrão de execução é de 300 segundos. Um script que excede esse limite indica a necessidade de simplificar a lógica.

• Divida operações complexas em vários scripts menores em vez de usar um único script grande.

Limpar o cache de scripts com segurança

Use SCRIPT FLUSH para remover todos os scripts em cache. Após a limpeza, qualquer chamada para EVALSHA ou EVALSHA_RO retornará um erro NOSCRIPT até que os scripts sejam recarregados.

SCRIPT FLUSH

Saída:

OK

Mantenha o source dos scripts em sua aplicação e implemente recuperação automática para erros NOSCRIPT. Em caso de erro, recarregue o script com SCRIPT LOAD ou registre-o novamente com EVAL.