channels-redis

Warnings

• breaking Version 4.0.0 migrated from `aioredis` to `redis-py`. This changed the configuration for `hosts`; specifying hosts as tuples is no longer supported, and for dicts, only the `address` key is considered. Pass `password` inline in the URI.
  Fix: Update `CHANNEL_LAYERS['default']['CONFIG']['hosts']` to use URI strings (e.g., 'redis://localhost:6379') or dicts with an 'address' key. Ensure `redis-py` is at least 4.5.3.
• deprecated The `asgi_redis` package is an older name for channels-redis and is intended for Channels 1.x projects. Do not use it for Channels 2.x+ projects.
  Fix: For Channels 2.x and newer, install and use `channels-redis` instead of `asgi_redis`.
• gotcha The `RedisPubSubChannelLayer` is currently in Beta status. This means it may be subject to breaking changes as it matures. Use with caution in production environments where stability is paramount.
• breaking Channels-redis 4.x dropped support for older Python and Django versions. Python 3.8 support was dropped in 4.3.0, and Python 3.7 was dropped in 4.2.0. Minimum Django version is 4.2.2 for `channels-redis` 4.3.0.
  Fix: Ensure your project uses Python 3.9+ and Django 4.2.2+ to be compatible with channels-redis 4.3.0. Refer to specific changelogs for minimum version requirements for other 4.x releases.
• gotcha When using `async_to_sync()` with `redis-py 4.x`, ensure that Redis connections are manually closed when an event loop shuts down to avoid warnings or resource leaks. This was addressed for the pub-sub layer in 4.1.0 but remains a general consideration.
  Fix: Implement explicit connection closing mechanisms where `async_to_sync` is used, especially if managing custom connection pools or unusual application lifecycles.
• gotcha When using sharding, passing multiple hosts to `CONFIG['hosts']` enables sharding. However, changing this host list can lead to loss of some sharded data. All servers talking to the same layer should have the same prefix and host list.
  Fix: Plan your Redis sharding configuration carefully and avoid frequent changes to the `hosts` list in production. Ensure consistent configuration across all application instances.

Install

• pip install channels-redis Install latest version

Imports

• RedisChannelLayer

  from channels_redis.core import RedisChannelLayer

  While older tutorials or Channels 1.x might imply a direct import from channels.layers, the correct and current import path for the Redis-backed layer is from channels_redis.core.
• RedisPubSubChannelLayer

  from channels_redis.pubsub import RedisPubSubChannelLayer

  This is a newer, beta-status layer that leverages Redis Pub/Sub for message dispatch.

Quickstart

To use channels-redis, you typically configure your `CHANNEL_LAYERS` setting in `settings.py` and set up your ASGI application in `asgi.py`. Ensure a Redis server (version 5.0 or higher) is running. This example shows a basic setup for the default `RedisChannelLayer` and a structure for `asgi.py`. You would further define `websocket_urlpatterns` in your app's `routing.py` and include it in the `URLRouter`.

import os
from django.core.asgi import get_asgi_application
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from django.conf import settings

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "your_project.settings")

# In your settings.py (e.g., your_project/settings.py):
# CHANNEL_LAYERS = {
#     "default": {
#         "BACKEND": "channels_redis.core.RedisChannelLayer",
#         "CONFIG": {
#             "hosts": [os.environ.get('REDIS_URL', 'redis://localhost:6379')],
#         },
#     },
# }

# Example routing (your_project/routing.py)
# from django.urls import re_path
# from chat.consumers import ChatConsumer
# websocket_urlpatterns = [
#     re_path(r'ws/chat/(?P<room_name>\w+)/$', ChatConsumer.as_asgi()),
# ]

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": AuthMiddlewareStack(
        URLRouter(
            # Replace with your app's websocket_urlpatterns
            # Example: chat.routing.websocket_urlpatterns
            [] # Placeholder for actual URLRouter patterns
        )
    ),
})