redis-connector: Utilitaires de connexion pour lua-resty-redis

Installation

Si vous n'avez pas configuré l'abonnement au dépôt RPM, inscrivez-vous. Ensuite, vous pouvez procéder avec les étapes suivantes.

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

Pour utiliser cette bibliothèque Lua avec NGINX, assurez-vous que nginx-module-lua est installé.

Ce document décrit lua-resty-redis-connector v0.11.0 publié le 13 juillet 2021.

Utilitaires de connexion pour lua-resty-redis, facilitant et rendant fiable la connexion aux hôtes Redis, soit directement, soit via Redis Sentinel.

Synopsis

Connexion authentifiée rapide et simple sur localhost à la DB 2 :

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

Configuration plus détaillée, avec des délais d'attente et un mot de passe par défaut :

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)  -- utilise les paramètres de keepalive

Conservez toute la configuration dans une table, pour créer / fermer facilement des connexions selon les besoins :

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 peut être utilisé pour remplacer certains paramètres par défaut donnés dans new, qui sont pertinents uniquement pour cette connexion.

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

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

Format DSN

Si le champ params.url est présent, il sera analysé pour définir les autres paramètres. Tous les paramètres spécifiés manuellement remplaceront les valeurs données dans le DSN.

Remarque : il s'agit d'un changement de comportement à partir de v0.06. Auparavant, les valeurs DSN prenaient la priorité.

Connexions Redis directes

Le format pour se connecter directement à Redis est :

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

Les champs USERNAME, PASSWORD et DB sont optionnels, tous les autres composants sont requis.

L'utilisation d'un nom d'utilisateur nécessite Redis 6.0.0 ou plus récent.

Connexions via Redis Sentinel

Lors de la connexion via Redis Sentinel, le format est le suivant :

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

Encore une fois, USERNAME, PASSWORD et DB sont optionnels. ROLE doit être soit m soit s pour maître / esclave respectivement.

Sur les versions de Redis plus récentes que 5.0.1, les Sentinelles peuvent optionnellement exiger leur propre mot de passe. Si activé, fournissez ce mot de passe dans le paramètre sentinel_password. Sur Redis 6.2.0 et plus récent, vous pouvez passer le nom d'utilisateur en utilisant le paramètre sentinel_username.

Une table de sentinels doit également être fournie. par exemple :

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

Mode Proxy

Activez le paramètre connection_is_proxied si vous vous connectez à Redis via un service proxy (par exemple, Twemproxy). Ces proxies ne prennent généralement en charge qu'un sous-ensemble limité des commandes Redis, celles qui ne nécessitent pas d'état et n'affectent pas plusieurs clés. Les bases de données et les transactions ne sont également pas prises en charge.

Le mode proxy désactivera le changement de DB lors de la connexion. Les commandes non prises en charge (par défaut celles non prises en charge par Twemproxy) retourneront nil, err immédiatement plutôt que d'être envoyées au proxy, ce qui peut entraîner des connexions perdues.

discard ne sera pas envoyé lors de l'ajout de connexions au pool de keepalive.

Commandes désactivées

Si configuré en tant que table de commandes, les méthodes de commande seront remplacées par une fonction qui retourne immédiatement nil, err sans transmettre la commande au serveur.

Paramètres par défaut

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

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

    host = "127.0.0.1",
    port = "6379",
    path = "",  -- chemin du socket unix, par 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 = {},
}

new

syntax: rc = redis_connector.new(params)

Crée l'objet Redis Connector, remplaçant les paramètres par défaut par ceux donnés. En cas d'échec, retourne nil et une chaîne décrivant l'erreur.

connect

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

Tente de créer une connexion, selon les params fournis, en revenant aux valeurs par défaut données dans new ou les valeurs par défaut prédéfinies. Si une connexion ne peut pas être établie, retourne nil et une chaîne décrivant la raison.

Notez que les params donnés ici ne changent pas la configuration propre du connecteur, et ne sont utilisés que pour modifier cette opération de connexion particulière. En tant que tel, les paramètres suivants n'ont aucun sens lorsqu'ils sont donnés dans connect.

keepalive_poolsize
keepalive_timeout
connection_is_proxied
disabled_commands

set_keepalive

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

Tente de placer la connexion Redis donnée dans le pool de keepalive, selon les délais d'attente et les paramètres de poolsize donnés dans new ou les valeurs par défaut prédéfinies.

Cela permet à une application de libérer des ressources sans avoir à suivre les paramètres de keepalive à l'échelle de l'application.

Retourne 1 ou en cas d'erreur, nil et une chaîne décrivant l'erreur.

Utilities

Les méthodes suivantes ne sont généralement pas nécessaires, mais peuvent être utiles si une interface personnalisée est requise.

connect_via_sentinel

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

Retourne une connexion Redis en accédant d'abord à une sentinelle comme fourni par la table params.sentinels, et en interrogeant cela avec params.master_name et params.role.

try_hosts

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

Essaie les hôtes fournis dans l'ordre et retourne la première connexion réussie.

connect_to_host

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

Tente de se connecter à l'host fourni.

sentinel.get_master

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

Étant donné une instance Sentinel connectée et un nom de maître, retournera l'instance Redis maître actuelle.

sentinel.get_slaves

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

Étant donné une instance Sentinel connectée et un nom de maître, retournera une liste des instances Redis esclaves enregistrées.

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-redis-connector.