django-redis

Install the django-redis package using pip.

$ python -m pip install django-redis

To use Redis Sentinels, set DJANGO_REDIS_CONNECTION_FACTORY to 'django_redis.pool.SentinelConnectionFactory' and configure the SENTINELS list and CLIENT_CLASS in your cache settings.

DJANGO_REDIS_CONNECTION_FACTORY = 'django_redis.pool.SentinelConnectionFactory'

SENTINELS = [
    ('sentinel-1', 26379),
    ('sentinel-2', 26379),
    ('sentinel-3', 26379),
]

CACHES = {
    "sentinel": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://service_name/db",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.SentinelClient",
            "SENTINELS": SENTINELS,
            "CONNECTION_POOL_CLASS": "redis.sentinel.SentinelConnectionPool",
        },
    },
}

You can use django-redis for session storage by configuring Django to use the cache-based session engine and pointing it to your redis-backed cache alias.

SESSION_ENGINE = "django.contrib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"

To use django-redis as your Django cache backend, update your CACHES setting in settings.py. Use django_redis.cache.RedisCache as the BACKEND and provide a connection string in the LOCATION field using redis-py URL notation.

Supported URL schemes:

• redis://: Normal TCP socket connection.
• rediss://: SSL wrapped TCP socket connection.
• unix://: Unix Domain Socket connection.

You can specify the database number via a db query string parameter (e.g., redis://localhost?db=0) or as the path in a redis:// URL (e.g., redis://localhost/0).

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
    }
}

To emulate Memcached behavior where the application does not crash if the cache server is down, set IGNORE_EXCEPTIONS to True in the cache OPTIONS.

Alternatively, you can set a global flag in your Django settings: DJANGO_REDIS_IGNORE_EXCEPTIONS = True.

CACHES = {
    "default": {
        # ...
        "OPTIONS": {
            "IGNORE_EXCEPTIONS": True,
        }
    }
}

By default, django-redis uses pickle.DEFAULT_PROTOCOL. To ensure compatibility or use a specific version, set the PICKLE_VERSION option in your cache configuration. Setting it to -1 will use the highest protocol version available.

CACHES = {
    "default": {
        # ...
        "OPTIONS": {
            "PICKLE_VERSION": -1  # Will use highest protocol version available
        }
    }
}

You can extend the default client behavior by setting CLIENT_CLASS in OPTIONS:

• ShardClient: Implements client-side sharding. (Experimental)
• HerdClient: Helps mitigate the thundering herd problem. Supports CACHE_HERD_TIMEOUT setting.
• DefaultClient: Supports replication by providing a list of LOCATION strings (primary followed by replicas).

# Shard Client
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": [
            "redis://127.0.0.1:6379/1",
            "redis://127.0.0.1:6379/2",
        ],
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.ShardClient",
        }
    }
}

# Herd Client
CACHES = {
    "default": {
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.HerdClient",
        }
    }
}

To connect to a Redis server using TLS with a self-signed certificate, use the rediss:// scheme and disable certificate verification by setting ssl_cert_reqs: None in CONNECTION_POOL_KWARGS.

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "rediss://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "CONNECTION_POOL_KWARGS": {"ssl_cert_reqs": None}
        }
    }
}

Customize the underlying redis-py connection pool via CONNECTION_POOL_KWARGS in the OPTIONS dictionary. You can also provide a custom connection pool class using CONNECTION_POOL_CLASS.

# Customize max connections and retry behavior
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "OPTIONS": {
            "CONNECTION_POOL_KWARGS": {
                "max_connections": 100,
                "retry_on_timeout": True
            }
        }
    }
}

# Use a custom connection pool subclass
CACHES = {
    "default": {
        "OPTIONS": {
            "CONNECTION_POOL_CLASS": "myproj.mypool.MyOwnPool",
        }
    }
}

Change the serialization format by setting the SERIALIZER option in OPTIONS. Supported serializers include:

• django_redis.serializers.json.JSONSerializer (JSON)
• django_redis.serializers.msgpack.MSGPackSerializer (Requires msgpack library)
• Default is pickle.

CACHES = {
    "default": {
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "SERIALIZER": "django_redis.serializers.json.JSONSerializer",
        }
    }
}

When IGNORE_EXCEPTIONS is enabled, you can log these errors using:

• DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS = True (Global setting)
• DJANGO_REDIS_LOGGER = 'some.specified.logger' (Global setting to specify the logger name/path)