Description

============================== Redis cache backend for Django ============================== .. image:: https://jazzband.co/static/img/badge.svg :target: https://jazzband.co/ :alt: Jazzband .. image:: https://github.com/jazzband/django-redis/actions/workflows/ci.yml/badge.svg :target: https://github.com/jazzband/django-redis/actions/workflows/ci.yml :alt: GitHub Actions .. image:: https://codecov.io/gh/jazzband/django-redis/branch/master/graph/badge.svg :target: https://codecov.io/gh/jazzband/django-redis :alt: Coverage .. image:: https://img.shields.io/pypi/v/django-redis.svg?style=flat :target: https://pypi.org/project/django-redis/ This is a `Jazzband <https://jazzband.co>`_ project. By contributing you agree to abide by the `Contributor Code of Conduct <https://jazzband.co/about/conduct>`_ and follow the `guidelines <https://jazzband.co/about/guidelines>`_. Introduction ------------ django-redis is a BSD licensed, full featured Redis cache and session backend for Django. Why use django-redis? ~~~~~~~~~~~~~~~~~~~~~ - Uses native redis-py url notation connection strings - Pluggable clients - Pluggable parsers - Pluggable serializers - Primary/secondary support in the default client - Comprehensive test suite - Used in production in several projects as cache and session storage - Supports infinite timeouts - Facilities for raw access to Redis client/connection pool - Highly configurable (can emulate memcached exception behavior, for example) - Unix sockets supported by default Requirements ~~~~~~~~~~~~ - `Python`_ 3.9+ - `Django`_ 4.2+ - `redis-py`_ 4.0.2+ - `Redis server`_ 2.8+ .. _Python: https://www.python.org/downloads/ .. _Django: https://www.djangoproject.com/download/ .. _redis-py: https://pypi.org/project/redis/ .. _Redis server: https://redis.io/download User guide ---------- Installation ~~~~~~~~~~~~ Install with pip: .. code-block:: console $ python -m pip install django-redis Configure as cache backend ~~~~~~~~~~~~~~~~~~~~~~~~~~ To start using django-redis, you should change your Django cache settings to something like: .. code-block:: python CACHES = { "default": { "BACKEND": "django_redis.cache.RedisCache", "LOCATION": "redis://127.0.0.1:6379/1", "OPTIONS": { "CLIENT_CLASS": "django_redis.client.DefaultClient", } } } django-redis uses the redis-py native URL notation for connection strings, it allows better interoperability and has a connection string in more "standard" way. Some examples: - ``redis://[[username]:[password]]@localhost:6379/0`` - ``rediss://[[username]:[password]]@localhost:6379/0`` - ``unix://[[username]:[password]]@/path/to/socket.sock?db=0`` Three URL schemes are supported: - ``redis://``: creates a normal TCP socket connection - ``rediss://``: creates a SSL wrapped TCP socket connection - ``unix://`` creates a Unix Domain Socket connection There are several ways to specify a database number: - A ``db`` querystring option, e.g. ``redis://localhost?db=0`` - If using the ``redis://`` scheme, the path argument of the URL, e.g. ``redis://localhost/0`` When using `Redis' ACLs <https://redis.io/topics/acl>`_, you will need to add the username to the URL (and provide the password with the Cache ``OPTIONS``). The login for the user ``django`` would look like this: .. code-block:: python CACHES = { "default": { "BACKEND": "django_redis.cache.RedisCache", "LOCATION": "redis://django@localhost:6379/0", "OPTIONS": { "CLIENT_CLASS": "django_redis.client.DefaultClient", "PASSWORD": "mysecret" } } } An alternative would be write both username and password into the URL: .. code-block:: python CACHES = { "default": { "BACKEND": "django_redis.cache.RedisCache", "LOCATION": "redis://django:mysecret@localhost:6379/0", "OPTIONS": { "CLIENT_CLASS": "django_redis.client.DefaultClient", } } } In some circumstances the password you should use to connect Redis is not URL-safe, in this case you can escape it or just use the convenience option in ``OPTIONS`` dict: .. code-block:: python CACHES = { "default": { "BACKEND": "django_redis.cache.RedisCache", "LOCATION": "redis://127.0.0.1:6379/1", "OPTIONS": { "CLIENT_CLASS": "django_redis.client.DefaultClient", "PASSWORD": "mysecret" } } } Take care, that this option does not overwrites the password in the uri, so if you have set the password in the uri, this settings will be ignored. Configure as session backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Django can by default use any cache backend as session backend and you benefit from that by using django-redis as backend for session storage without installing any additio