diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internals/contributing/writing-code/unit-tests.txt | 7 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 5 | ||||
| -rw-r--r-- | docs/releases/4.0.txt | 10 | ||||
| -rw-r--r-- | docs/spelling_wordlist | 1 | ||||
| -rw-r--r-- | docs/topics/cache.txt | 93 |
5 files changed, 110 insertions, 6 deletions
diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 6a5bd5ab8f..9bba72c451 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -285,6 +285,7 @@ dependencies: * PyYAML_ * pytz_ (required) * pywatchman_ +* redis_ * setuptools_ * memcached_, plus a :ref:`supported Python binding <memcached>` * gettext_ (:ref:`gettext_on_windows`) @@ -308,8 +309,9 @@ encounter. You can also install the database adapter(s) of your choice using ``oracle.txt``, ``mysql.txt``, or ``postgres.txt``. -If you want to test the memcached cache backend, you'll also need to define -a :setting:`CACHES` setting that points at your memcached instance. +If you want to test the memcached or Redis cache backends, you'll also need to +define a :setting:`CACHES` setting that points at your memcached or Redis +instance respectively. To run the GeoDjango tests, you will need to :doc:`set up a spatial database and install the Geospatial libraries</ref/contrib/gis/install/index>`. @@ -332,6 +334,7 @@ service. .. _PyYAML: https://pyyaml.org/wiki/PyYAML .. _pytz: https://pypi.org/project/pytz/ .. _pywatchman: https://pypi.org/project/pywatchman/ +.. _redis: https://pypi.org/project/redis/ .. _setuptools: https://pypi.org/project/setuptools/ .. _memcached: https://memcached.org/ .. _gettext: https://www.gnu.org/software/gettext/manual/gettext.html diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 12d89142d1..0c5b3fe307 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -153,6 +153,7 @@ The cache backend to use. The built-in cache backends are: * ``'django.core.cache.backends.locmem.LocMemCache'`` * ``'django.core.cache.backends.memcached.PyMemcacheCache'`` * ``'django.core.cache.backends.memcached.PyLibMCCache'`` +* ``'django.core.cache.backends.redis.RedisCache'`` You can use a cache backend that doesn't ship with Django by setting :setting:`BACKEND <CACHES-BACKEND>` to a fully-qualified path of a cache @@ -162,6 +163,10 @@ backend class (i.e. ``mypackage.backends.whatever.WhateverCache``). The ``PyMemcacheCache`` backend was added. +.. versionchanged:: 4.0 + + The ``RedisCache`` backend was added. + .. setting:: CACHES-KEY_FUNCTION ``KEY_FUNCTION`` diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt index 709363a08f..540500af47 100644 --- a/docs/releases/4.0.txt +++ b/docs/releases/4.0.txt @@ -65,6 +65,16 @@ The new :ref:`scrypt password hasher <scrypt-usage>` is more secure and recommended over PBKDF2. However, it's not the default as it requires OpenSSL 1.1+ and more memory. +Redis cache backend +------------------- + +The new ``django.core.cache.backends.redis.RedisCache`` cache backend provides +built-in support for caching with Redis. `redis-py`_ 3.0.0 or higher is +required. For more details, see the :ref:`documentation on caching with Redis +in Django <redis>`. + +.. _`redis-py`: https://pypi.org/project/redis/ + Minor features -------------- diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index bd8785cf67..8d9b17a43d 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -423,6 +423,7 @@ recomputation recursed redeclare redirections +redis redisplay redisplayed redisplaying diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index 0f25260672..3bc35fd51d 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -62,7 +62,6 @@ settings file. Here's an explanation of all available values for Memcached --------- -The fastest, most efficient type of cache supported natively by Django, Memcached__ is an entirely memory-based cache server, originally developed to handle high loads at LiveJournal.com and subsequently open-sourced by Danga Interactive. It is used by sites such as Facebook and Wikipedia to @@ -169,6 +168,71 @@ particularly temporary. some problems and seems to be unmaintained. Use ``PyMemcacheCache`` or ``PyLibMCCache`` instead. +.. _redis: + +Redis +----- + +.. versionadded:: 4.0 + +Redis__ is an in-memory database that can be used for caching. To begin you'll +need a Redis server running either locally or on a remote machine. + +__ https://redis.io/ + +After setting up the Redis server, you'll need to install Python bindings for +Redis. `redis-py`_ is the binding supported natively by Django. Installing the +additional `hiredis-py`_ package is also recommended. + +.. _`redis-py`: https://pypi.org/project/redis/ +.. _`hiredis-py`: https://pypi.org/project/hiredis/ + +To use Redis as your cache backend with Django: + +* Set :setting:`BACKEND <CACHES-BACKEND>` to + ``django.core.cache.backends.redis.RedisCache``. + +* Set :setting:`LOCATION <CACHES-LOCATION>` to the URL pointing to your Redis + instance, using the appropriate scheme. See the ``redis-py`` docs for + `details on the available schemes + <https://redis-py.readthedocs.io/en/stable/#redis.ConnectionPool.from_url>`_. + +For example, if Redis is running on localhost (127.0.0.1) port 6379:: + + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.redis.RedisCache', + 'LOCATION': 'redis://127.0.0.1:6379', + } + } + +Often Redis servers are protected with authentication. In order to supply a +username and password, add them in the ``LOCATION`` along with the URL:: + + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.redis.RedisCache', + 'LOCATION': 'redis://username:password@127.0.0.1:6379', + } + } + +If you have multiple Redis servers set up in the replication mode, you can +specify the servers either as a semicolon or comma delimited string, or as a +list. While using multiple servers, write operations are performed on the first +server (leader). Read operations are performed on the other servers (replicas) +chosen at random:: + + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.redis.RedisCache', + 'LOCATION': [ + 'redis://127.0.0.1:6379', # leader + 'redis://127.0.0.1:6378', # read-replica 1 + 'redis://127.0.0.1:6377', # read-replica 2 + ], + } + } + .. _database-caching: Database caching @@ -422,9 +486,9 @@ behavior. These arguments are provided as additional keys in the On some backends (``database`` in particular) this makes culling *much* faster at the expense of more cache misses. - Memcached backends pass the contents of :setting:`OPTIONS <CACHES-OPTIONS>` - as keyword arguments to the client constructors, allowing for more advanced - control of client behavior. For example usage, see below. + The Memcached and Redis backends pass the contents of :setting:`OPTIONS + <CACHES-OPTIONS>` as keyword arguments to the client constructors, allowing + for more advanced control of client behavior. For example usage, see below. * :setting:`KEY_PREFIX <CACHES-KEY_PREFIX>`: A string that will be automatically included (prepended by default) to all cache keys @@ -496,6 +560,27 @@ flag on the connection's socket:: } } +Here's an example configuration for a ``redis`` based backend that selects +database ``10`` (by default Redis ships with 16 logical databases), specifies a +`parser class`_ (``redis.connection.HiredisParser`` will be used by default if +the ``hiredis-py`` package is installed), and sets a custom `connection pool +class`_ (``redis.ConnectionPool`` is used by default):: + + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.redis.RedisCache', + 'LOCATION': 'redis://127.0.0.1:6379', + 'OPTIONS': { + 'db': '10', + 'parser_class': 'redis.connection.PythonParser', + 'pool_class': 'redis.BlockingConnectionPool', + } + } + } + +.. _`parser class`: https://github.com/andymccurdy/redis-py#parsers +.. _`connection pool class`: https://github.com/andymccurdy/redis-py#connection-pools + .. _the-per-site-cache: The per-site cache |