Pular para conteúdo

redis-connector: Utilitários de conexão para lua-resty-redis

Instalação

Se você ainda não configurou a assinatura do repositório RPM, inscreva-se. Em seguida, você pode prosseguir com os seguintes passos.

CentOS/RHEL 7 ou Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-redis-connector

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-redis-connector

Para usar esta biblioteca Lua com NGINX, certifique-se de que o nginx-module-lua esteja instalado.

Este documento descreve o lua-resty-redis-connector v0.11.0 lançado em 13 de julho de 2021.

Utilitários de conexão para lua-resty-redis, facilitando e tornando confiável a conexão com hosts Redis, seja diretamente ou via Redis Sentinel.

Sinopse

Conexão autenticada rápida e simples no localhost para o DB 2:

local redis, err = require("resty.redis.connector").new({
    url = "redis://[email protected]:6379/2",
}):connect()

Configuração mais detalhada, com timeouts e uma senha padrão:

local rc = require("resty.redis.connector").new({
    connect_timeout = 50,
    send_timeout = 5000,
    read_timeout = 5000,
    keepalive_timeout = 30000,
    password = "mypass",
})

local redis, err = rc:connect({
    url = "redis://127.0.0.1:6379/2",
})

-- ...

local ok, err = rc:set_keepalive(redis)  -- usa parâmetros de keepalive

Mantenha toda a configuração em uma tabela, para criar / fechar conexões facilmente conforme necessário:

local rc = require("resty.redis.connector").new({
    connect_timeout = 50,
    send_timeout = 5000,
    read_timeout = 5000,
    keepalive_timeout = 30000,

    host = "127.0.0.1",
    port = 6379,
    db = 2,
    password = "mypass",
})

local redis, err = rc:connect()

-- ...

local ok, err = rc:set_keepalive(redis)

connect pode ser usado para substituir alguns padrões dados em new, que são pertinentes apenas a esta conexão.

local rc = require("resty.redis.connector").new({
    host = "127.0.0.1",
    port = 6379,
    db = 2,
})

local redis, err = rc:connect({
    db = 5,
})

Formato DSN

Se o campo params.url estiver presente, ele será analisado para definir os outros parâmetros. Quaisquer parâmetros especificados manualmente substituirão os valores dados no DSN.

Nota: esta é uma mudança de comportamento a partir da v0.06. Anteriormente, os valores do DSN teriam precedência.

Conexões diretas com Redis

O formato para conectar-se diretamente ao Redis é:

redis://USERNAME:PASSWORD@HOST:PORT/DB

Os campos USERNAME, PASSWORD e DB são opcionais, todos os outros componentes são obrigatórios.

O uso de nome de usuário requer Redis 6.0.0 ou mais recente.

Conexões via Redis Sentinel

Ao conectar-se via Redis Sentinel, o formato é o seguinte:

sentinel://USERNAME:PASSWORD@MASTER_NAME:ROLE/DB

Novamente, USERNAME, PASSWORD e DB são opcionais. ROLE deve ser m ou s para mestre / escravo, respectivamente.

Em versões do Redis mais recentes que 5.0.1, os Sentinels podem opcionalmente exigir sua própria senha. Se ativado, forneça essa senha no parâmetro sentinel_password. No Redis 6.2.0 e mais recente, você pode passar o nome de usuário usando o parâmetro sentinel_username.

Uma tabela de sentinels também deve ser fornecida. Ex.:

local redis, err = rc:connect{
    url = "sentinel://mymaster:a/2",
    sentinels = {
        { host = "127.0.0.1", port = 26379 },
    },
    sentinel_username = "default",
    sentinel_password = "password"
}

Modo Proxy

Ative o parâmetro connection_is_proxied se conectar ao Redis através de um serviço proxy (por exemplo, Twemproxy). Esses proxies geralmente suportam apenas um subconjunto limitado de comandos Redis, aqueles que não requerem estado e não afetam várias chaves. Bancos de dados e transações também não são suportados.

O modo proxy desativará a troca para um DB na conexão. Comandos não suportados (padrão para aqueles não suportados pelo Twemproxy) retornarão nil, err imediatamente em vez de serem enviados para o proxy, o que pode resultar em conexões perdidas.

discard não será enviado ao adicionar conexões ao pool de keepalive.

Comandos Desativados

Se configurado como uma tabela de comandos, os métodos de comando serão substituídos por uma função que retorna imediatamente nil, err sem encaminhar o comando para o servidor.

Parâmetros Padrão

{
    connect_timeout = 100,
    send_timeout = 1000,
    read_timeout = 1000,
    keepalive_timeout = 60000,
    keepalive_poolsize = 30,

    -- ssl, ssl_verify, server_name, pool, pool_size, backlog
    -- veja: https://github.com/openresty/lua-resty-redis#connect
    connection_options = {},

    host = "127.0.0.1",
    port = "6379",
    path = "",  -- caminho do socket unix, ex. /tmp/redis.sock
    username = "",
    password = "",
    sentinel_username = "",
    sentinel_password = "",
    db = 0,

    master_name = "mymaster",
    role = "master",  -- master | slave
    sentinels = {},

    connection_is_proxied = false,

    disabled_commands = {},
}

API

new

syntax: rc = redis_connector.new(params)

Cria o objeto Redis Connector, substituindo os parâmetros padrão pelos fornecidos. Em caso de falhas, retorna nil e uma string descrevendo o erro.

connect

syntax: redis, err = rc:connect(params)

Tenta criar uma conexão, de acordo com os params fornecidos, recorrendo aos padrões dados em new ou aos padrões predefinidos. Se uma conexão não puder ser estabelecida, retorna nil e uma string descrevendo o motivo.

Observe que os params dados aqui não alteram a configuração própria do conector e são usados apenas para alterar esta operação de conexão específica. Assim, os seguintes parâmetros não têm significado quando dados em connect.

  • keepalive_poolsize
  • keepalive_timeout
  • connection_is_proxied
  • disabled_commands

set_keepalive

syntax: ok, err = rc:set_keepalive(redis)

Tenta colocar a conexão Redis dada no pool de keepalive, de acordo com os parâmetros de timeout e poolsize dados em new ou os padrões predefinidos.

Isso permite que uma aplicação libere recursos sem precisar acompanhar as configurações de keepalive em toda a aplicação.

Retorna 1 ou, em caso de erro, nil e uma string descrevendo o erro.

Utilities

Os seguintes métodos não são tipicamente necessários, mas podem ser úteis se uma interface personalizada for requerida.

connect_via_sentinel

syntax: redis, err = rc:connect_via_sentinel(params)

Retorna uma conexão Redis acessando primeiro um sentinel conforme fornecido pela tabela params.sentinels, e consultando isso com o params.master_name e params.role.

try_hosts

syntax: redis, err = rc:try_hosts(hosts)

Tenta os hosts fornecidos em ordem e retorna a primeira conexão bem-sucedida.

connect_to_host

syntax: redis, err = rc:connect_to_host(host)

Tenta conectar-se ao host fornecido.

sentinel.get_master

syntax: master, err = sentinel.get_master(sentinel, master_name)

Dada uma instância Sentinel conectada e um nome de mestre, retornará a instância Redis mestre atual.

sentinel.get_slaves

syntax: slaves, err = sentinel.get_slaves(sentinel, master_name)

Dada uma instância Sentinel conectada e um nome de mestre, retornará uma lista de instâncias Redis escravas registradas.

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-redis-connector.