| single |
==============================
Redis cache backend for Django
==============================
:alt: Jazzband
:alt: GitHub Actions
:alt: Coverage
This is a [Jazzband] project. By contributing you agree
to abide by the [Contributor Code of Conduct
] and follow the [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.6+
- `Django`_ 2.2+
- `redis-py`_ 3.0+
- `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:
|