Redis connection management for BullMQ.

This module provides a supervised Redis connection pool using NimblePool. It handles connection lifecycle, reconnection, and provides a clean API for executing Redis commands.

Connection Behavior

This module follows the same philosophy as Redix:

• Supervised connections - Connections are started under a supervisor and automatically reconnect when the TCP connection drops.

• Fail-fast - Commands fail immediately with {:error, reason} if the connection is unavailable. No hidden retries are performed.

• Caller handles retries - It's the caller's responsibility to decide whether to retry failed commands. BullMQ's Worker handles retries for job processing automatically.

This design follows Erlang/OTP principles: let the connection supervision handle reconnection, and let callers decide retry policy based on their specific needs.

Error Handling

Commands return {:error, reason} on failure. Common errors include:

• %Redix.ConnectionError{reason: :closed} - Connection is down
• %Redix.ConnectionError{reason: :timeout} - Command timed out
• %Redix.Error{} - Redis returned an error (e.g., wrong type)

Example handling:

case BullMQ.RedisConnection.command(conn, ["GET", "key"]) do
  {:ok, value} -> value
  {:error, %Redix.ConnectionError{}} -> :connection_error
  {:error, %Redix.Error{message: msg}} -> {:redis_error, msg}
  {:error, reason} -> {:error, reason}
end

Usage

Add to your supervision tree:

children = [
  {BullMQ.RedisConnection,
    name: :bullmq_redis,
    url: "redis://localhost:6379",
    pool_size: 10}
]

Then use it with queues and workers:

BullMQ.Queue.add("my_queue", "job", %{}, connection: :bullmq_redis)

Lua Script Loading

BullMQ uses Lua scripts for atomic Redis operations. All scripts are automatically loaded into Redis's script cache when the connection starts. This ensures the connection is fully ready for BullMQ operations (Worker, Queue, QueueEvents, etc.) before it's used.

Unlike Node.js BullMQ which uses ioredis's defineCommand to register scripts on the client, the Elixir version loads scripts via SCRIPT LOAD during initialization and uses EVALSHA for execution with automatic EVAL fallback on NOSCRIPT errors (in case Redis was restarted and lost its script cache).

Options

• :name - The name to register the connection pool (required)
• :url - Redis URL (e.g., "redis://localhost:6379")
• :host - Redis host (default: "localhost")
• :port - Redis port (default: 6379)
• :password - Redis password (optional)
• :database - Redis database number (default: 0)
• :pool_size - Number of connections in the pool (default: 10)
• :ssl - Enable SSL (default: false)
• :socket_opts - Additional socket options
• :timeout - Connection timeout in ms (default: 5000)