Redis Connection Management#

Redis is a central dependency in Dify, used for caching, distributed locking, pub/sub event delivery (SSE streams, Socket.IO collaboration), and Celery task brokering. Connection configuration lives in RedisConfig (Pydantic BaseSettings, all fields readable from env vars), and the client is initialized in ext_redis.py.

Configuration Reference#

All settings are in api/configs/middleware/cache/redis_config.py.

Connection basics 1

• REDIS_HOST (default localhost), REDIS_PORT (default 6379), REDIS_DB (default 0)
• REDIS_USERNAME, REDIS_PASSWORD — optional auth
• REDIS_KEY_PREFIX — global prefix applied to all keys/channel names; prevents cross-deployment collisions on shared instances

Timeouts & pool 1

• REDIS_SOCKET_TIMEOUT (default 5.0s) — per-operation read/write timeout
• REDIS_SOCKET_CONNECT_TIMEOUT (default 5.0s) — TCP connection establishment timeout
• REDIS_HEALTH_CHECK_INTERVAL (default 30s) — periodic ping to detect stale connections (not supported by Cluster; silently excluded)
• REDIS_MAX_CONNECTIONS — optional pool size cap

Retry policy 1 2

• REDIS_RETRY_RETRIES (default 3), REDIS_RETRY_BACKOFF_BASE (default 1.0s), REDIS_RETRY_BACKOFF_CAP (default 10.0s)
• Uses ExponentialWithJitterBackoff; retries on ConnectionError, TimeoutError, BrokenPipeError, OSError

TCP Keepalive — added in PR #38973 1

• REDIS_KEEPALIVE (default false) — enables TCP keepalive on the socket
• REDIS_KEEPALIVE_IDLE (default 30s), REDIS_KEEPALIVE_INTERVAL (default 10s), REDIS_KEEPALIVE_COUNT (default 10)
• Platform-specific: Linux sets TCP_KEEPIDLE / TCP_KEEPINTVL / TCP_KEEPCNT; macOS sets TCP_KEEPALIVE 3

SSL/TLS 1

• REDIS_USE_SSL — switches to SSLConnection and rediss:// scheme
• REDIS_SSL_CERT_REQS, REDIS_SSL_CA_CERTS, REDIS_SSL_CERTFILE, REDIS_SSL_KEYFILE

RESP protocol / client-side cache 1

• REDIS_SERIALIZATION_PROTOCOL (default 3)
• REDIS_ENABLE_CLIENT_SIDE_CACHE — requires RESP3; enforced at startup 4

Client Types#

init_app() selects one of three factory functions based on config flags:

Cluster caveat: health_check_interval is silently ignored by RedisCluster, so _get_cluster_connection_health_params() explicitly excludes it.

The global redis_client is a RedisClientWrapper that transparently prefixes all key/name arguments using REDIS_KEY_PREFIX and supports deferred initialization to handle Sentinel failover — the inner _client is only set once and can be swapped by re-calling initialize() 5.

Pub/Sub Clients#

A separate pub/sub client (_pubsub_redis_client) is initialized in init_app(). By default it reuses the main client. If PUBSUB_REDIS_URL is set, a dedicated client is created via _create_pubsub_client() — which supports both standalone and Cluster modes from a URL.

get_pubsub_broadcast_channel() returns one of three channel implementations based on PUBSUB_REDIS_CHANNEL_TYPE:

Ongoing refactor (PR #35515): A pending PR replaces the URL-based pub/sub config with a structured RedisConnectionSpec frozen dataclass. This will unify main and pub/sub client construction for all three topologies (including Sentinel HA for pub/sub, which silently degraded before) and replace PUBSUB_REDIS_URL with structured PUBSUB_REDIS_* fields. See PR #35515 6.

Socket.IO Integration#

ext_socketio.py uses socketio.RedisManager to fan out collaboration room events across API workers. The channel name is serialize_redis_name("socketio"), which applies REDIS_KEY_PREFIX for deployment isolation 7.

Critical: socket_timeout is intentionally omitted from RedisManager options 8. The RedisManager runs a blocking pubsub.listen() loop that idles between messages indefinitely; passing REDIS_SOCKET_TIMEOUT (default 5s) causes a reconnect storm every quiet 5-second window (TimeoutError → resubscribe), breaking collaboration event delivery. This was fixed in PR #39587. socket_connect_timeout is still passed to guard connection establishment.

Key Files#