Redis API

Redis connection helpers are available under ptool.redis and p.redis.

ptool.redis.connect

v0.9.0 - Introduced.

ptool.redis.connect(url_or_options) opens a Redis connection and returns a Connection object.

Arguments:

• url_or_options (string|table, required):
  • When a string is provided, it is treated as the Redis URL.
  • When a table is provided, it currently supports:
    • url (string, required): The Redis URL.

Common URL examples:

local redis = ptool.redis.connect("redis://127.0.0.1/")
local db1 = ptool.redis.connect("redis://127.0.0.1/1")
local auth = ptool.redis.connect({
  url = "redis://:[email protected]:6379/0",
})

Notes:

• The connection is intended for direct command execution through conn:call(...).
• This API does not currently provide dedicated pub/sub, pipeline, or transaction helpers.

Connection

v0.9.0 - Introduced.

Connection represents an open Redis connection returned by ptool.redis.connect().

It is implemented as a Lua userdata.

Methods:

• conn:call(command, ...) -> any
• conn:close() -> nil

Command argument rules:

• command must be a non-empty string.
• Remaining arguments are passed to Redis as a flat argument list.
• Supported argument value types are:
  • boolean
  • integer
  • number
  • string
• nil, tables, functions, threads, and userdata are not supported as Redis command arguments.
• Lua strings are passed as raw bytes, so binary-safe Redis values are supported.

Reply conversion rules:

• Null replies become nil.
• Integer replies become Lua integers.
• Bulk strings, simple strings, and verbatim strings become Lua strings.
• Array and set replies become dense Lua array tables.
• Map replies become Lua tables when the map keys can be represented as Lua strings, integers, numbers, or booleans.
• Double replies become Lua numbers.
• Boolean replies become Lua booleans.
• Big number replies become Lua strings.
• Push replies become tables shaped like { kind = "...", data = {...} }.

call

v0.9.0 - Introduced.

Canonical API name: ptool.redis.Connection:call.

conn:call(command, ...) sends a Redis command and returns the converted reply.

Example:

local redis = ptool.redis.connect("redis://127.0.0.1/")

redis:call("SET", "user:1:name", "alice")
print(redis:call("GET", "user:1:name")) -- alice

local count = redis:call("INCR", "counters:signup")
print(count)

local values = redis:call("MGET", "user:1:name", "missing")
print(values[1])        -- alice
print(values[2] == nil) -- true

close

v0.9.0 - Introduced.

Canonical API name: ptool.redis.Connection:close.

conn:close() closes the connection.

Behavior:

• After closing, the connection can no longer be used.