Skip to content

Configuration Reference

StreamClient

Param Default Description
host "localhost" Redis host
port 6379 Redis port
db 0 Redis DB index
username None AUTH username
password None AUTH password
prefix "" Key prefix prepended to all stream names ({prefix}_{stream})
max_connections 1000 Connection pool size
pool_timeout 5 Seconds to wait for a free connection
ssl False Enable TLS

Factory Methods

# Direct constructor
client = StreamClient(host="localhost", port=6379)

# From URL
client = StreamClient.from_url("redis://localhost:6379/0")
client = StreamClient.from_url("rediss://user:pass@host:6380/0")   # TLS

# Startup nodes
client = StreamClient.from_cluster(
    startup_nodes=[{"host": "node1", "port": 6379}],
    password="secret",
)

# From URL
client = StreamClient.from_url("redis+cluster://node1:6379")
client = StreamClient.from_url("rediss+cluster://node1:6380")      # TLS cluster

Cluster key rule

Stream and DLQ stream must share a hash tag to land on the same Redis slot:

stream="{orders}_main", dlq_stream="{orders}_dlq"

ConsumerConfig

Param Default Description
group required Consumer group name
worker_name auto Unique consumer name per pod. Auto = {group}_{hostname}_{rand4}
dlq_stream None Stream name to route poison pills and decode errors to
dlq_group None Consumer group for the DLQ stream
batch_size 100 Max messages per XREADGROUP / XAUTOCLAIM call
block_ms 5000 XREADGROUP block timeout (ms) — 0 = non-blocking
min_idle_claim_ms 10000 XAUTOCLAIM idle threshold (ms). Set to at least 2× max handler latency
max_deliveries 3 Delivery count before message is routed to DLQ
max_stream_size 100000 Approximate XADD MAXLEN trim
max_claim_passes None Max XAUTOCLAIM cursor iterations per run_once(). None = sweep full PEL. Set to 1 to restore single-pass behavior 
from redis_stream_queue import ConsumerConfig

config = ConsumerConfig(
    group="order_workers",
    dlq_stream="orders_dlq",
    batch_size=100,
    block_ms=5_000,
    min_idle_claim_ms=30_000,   # 2× max handler latency
    max_deliveries=3,
)