lua-resty-redis

To avoid race conditions and errors in a high-concurrency Nginx environment, follow these rules:

1. Do NOT store the resty.redis object in a Lua module-level variable. This will cause it to be shared across all concurrent requests in a worker process, leading to "socket busy" or "bad request" errors. Always use function local variables or the ngx.ctx table.
2. Context Restriction: This library cannot be used in Nginx phases where the cosocket API is unavailable, such as init_by_lua*, set_by_lua*, log_by_lua*, or header_filter_by_lua*.
3. Connection Pool Sizing: A good rule of thumb for set_keepalive is: pool_size = (Total Redis Max Connections) / (Nginx Workers * Nginx Instances).
4. Error Logging: If you implement custom error handling, disable Nginx's automatic socket error logging by setting lua_socket_log_errors off; in your Nginx configuration to avoid duplicate logs.

Pipelining allows you to send multiple commands to the server in a single run, reducing network round-trips.

Workflow:

1. Call red:init_pipeline() to enable mode.
2. Execute multiple Redis command methods (they will be cached locally).
3. Call red:commit_pipeline() to send all commands and receive all replies as a single multi-bulk reply.
4. Use red:cancel_pipeline() if you wish to discard the cached commands instead of executing them.

Return Values: commit_pipeline returns a Lua table containing the results of all commands. If a command fails, the corresponding element in the table will be {false, err_message}.

red:init_pipeline()
red:set("cat", "Marry")
red:set("horse", "Bob")
red:get("cat")
red:get("horse")

local results, err = red:commit_pipeline()
if not results then
    ngx.say("failed to commit: ", err)
    return
end

for i, res in ipairs(results) do
    if type(res) == "table" then
        if res[1] == false then
            ngx.say("command ", i, " failed: ", res[2])
        end
    else
        -- process scalar result
    end
end

To use lua-resty-redis, create a new object using redis:new(), set timeouts, and connect via IP, hostname, or Unix domain socket. Note that if connecting via hostname, you must specify a resolver in your Nginx configuration.

All Redis commands are available as lowercase methods on the redis object. Methods return the result and an error string on failure.

-- In nginx.conf
# resolver 8.8.8.8;

-- In content_by_lua_block
local redis = require "resty.redis"
local red = redis:new()

red:set_timeouts(1000, 1000, 1000) -- 1 sec

-- Connect via IP
local ok, err = red:connect("127.0.0.1", 6379)
if not ok then
    ngx.say("failed to connect: ", err)
    return
end

-- Use commands (e.g., SET)
ok, err = red:set("dog", "an animal")

-- Use commands (e.g., GET)
local res, err = red:get("dog")
if not res then
    ngx.say("failed to get dog: ", err)
    return
end

if res == ngx.null then
    ngx.say("dog not found.")
    return
end

ngx.say("dog: ", res)

The connect method allows connecting to a host/port or a Unix domain socket. It supports an optional options_table for advanced configuration.

Syntax:

• ok, err = red:connect(host, port, options_table?)
• ok, err = red:connect("unix:/path/to/unix.sock", options_table?)

Options Table Keys:

• ssl: Boolean. If true, uses SSL to connect (default: false).
• ssl_verify: Boolean. If true, verifies the server SSL certificate (default: false). Requires lua_ssl_trusted_certificate configuration.
• server_name: String. Specifies the SNI for TLS.
• pool: String. Custom name for the connection pool.
• pool_size: Number. Size of the connection pool (per Nginx worker). If omitted and backlog is provided, defaults to lua_socket_pool_size.
• backlog: Number. Limits the total number of opened connections for this pool. If the pool is full, connections are queued up to this limit.