redis-connector: Утилиты подключения для lua-resty-redis

Установка

Если вы еще не настроили подписку на RPM-репозиторий, зарегистрируйтесь. Затем вы можете продолжить с следующими шагами.

CentOS/RHEL 7 или 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

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что nginx-module-lua установлен.

Этот документ описывает lua-resty-redis-connector v0.11.0, выпущенный 13 июля 2021 года.

---

Утилиты подключения для lua-resty-redis, которые упрощают и делают надежным подключение к Redis-хостам, как напрямую, так и через Redis Sentinel.

Синопсис

Быстрое и простое аутентифицированное подключение к БД 2 на localhost:

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

Более подробная конфигурация с тайм-аутами и паролем по умолчанию:

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)  -- использует параметры keepalive

Храните всю конфигурацию в таблице, чтобы легко создавать / закрывать подключения по мере необходимости:

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 может использоваться для переопределения некоторых значений по умолчанию, заданных в new, которые относятся только к этому подключению.

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

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

Формат DSN

Если поле params.url присутствует, оно будет разобрано для установки других параметров. Любые вручную указанные параметры будут переопределять значения, заданные в DSN.

Примечание: это изменение поведения с версии v0.06. Ранее значения DSN имели приоритет.

Прямые подключения к Redis

Формат для прямого подключения к Redis:

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

Поля USERNAME, PASSWORD и DB являются необязательными, все остальные компоненты обязательны.

Использование имени пользователя требует Redis версии 6.0.0 или новее.

Подключения через Redis Sentinel

При подключении через Redis Sentinel формат следующий:

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

Снова, USERNAME, PASSWORD и DB являются необязательными. ROLE должен быть либо m, либо s для мастера / слейва соответственно.

В версиях Redis старше 5.0.1, Sentinel может дополнительно требовать свой собственный пароль. Если это включено, предоставьте этот пароль в параметре sentinel_password. В Redis 6.2.0 и новее вы можете передать имя пользователя с помощью параметра sentinel_username.

Также необходимо предоставить таблицу sentinels. Например:

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

Режим прокси

Включите параметр connection_is_proxied, если подключаетесь к Redis через прокси-сервис (например, Twemproxy). Эти прокси обычно поддерживают только ограниченный подмножество команд Redis, которые не требуют состояния и не затрагивают несколько ключей. Базы данных и транзакции также не поддерживаются.

Режим прокси отключит переключение на базу данных при подключении. Неподдерживаемые команды (по умолчанию те, которые не поддерживаются Twemproxy) будут возвращать nil, err немедленно, а не отправляться на прокси, что может привести к разрывам соединений.

discard не будет отправлен при добавлении подключений в пул keepalive.

Отключенные команды

Если настроены в виде таблицы команд, методы команд будут заменены функцией, которая немедленно возвращает nil, err без пересылки команды на сервер.

Параметры по умолчанию

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

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

    host = "127.0.0.1",
    port = "6379",
    path = "",  -- путь к unix-сокету, например, /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
• connect
• set_keepalive
• Утилиты
  • connect_via_sentinel
  • try_hosts
  • connect_to_host
  • sentinel.get_master
  • sentinel.get_slaves

new

синтаксис: rc = redis_connector.new(params)

Создает объект Redis Connector, переопределяя параметры по умолчанию на указанные. В случае неудачи возвращает nil и строку, описывающую ошибку.

connect

синтаксис: redis, err = rc:connect(params)

Пытается создать соединение в соответствии с предоставленными params, возвращаясь к значениям по умолчанию, заданным в new или предопределенным значениям. Если подключение не может быть установлено, возвращает nil и строку, описывающую причину.

Обратите внимание, что params, указанные здесь, не изменяют собственную конфигурацию коннектора и используются только для изменения этой конкретной операции подключения. Таким образом, следующие параметры не имеют значения, если указаны в connect.

• keepalive_poolsize
• keepalive_timeout
• connection_is_proxied
• disabled_commands

set_keepalive

синтаксис: ok, err = rc:set_keepalive(redis)

Пытается поместить данное соединение Redis в пул keepalive в соответствии с параметрами тайм-аута и размера пула, заданными в new или предопределенными значениями.

Это позволяет приложению освобождать ресурсы, не отслеживая настройки keepalive на уровне приложения.

Возвращает 1 или в случае ошибки nil и строку, описывающую ошибку.

Утилиты

Следующие методы обычно не нужны, но могут быть полезны, если требуется пользовательский интерфейс.

connect_via_sentinel

синтаксис: redis, err = rc:connect_via_sentinel(params)

Возвращает соединение Redis, сначала обращаясь к sentinel, указанному в таблице params.sentinels, и запрашивая его с помощью params.master_name и params.role.

try_hosts

синтаксис: redis, err = rc:try_hosts(hosts)

Пробует указанные хосты по порядку и возвращает первое успешное соединение.

connect_to_host

синтаксис: redis, err = rc:connect_to_host(host)

Пытается подключиться к указанному host.

sentinel.get_master

синтаксис: master, err = sentinel.get_master(sentinel, master_name)

Учитывая подключенный экземпляр Sentinel и имя мастера, вернет текущий экземпляр Redis мастера.

sentinel.get_slaves

синтаксис: slaves, err = sentinel.get_slaves(sentinel, master_name)

Учитывая подключенный экземпляр Sentinel и имя мастера, вернет список зарегистрированных экземпляров Redis слейвов.

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-redis-connector.