[4.1.x] Fixed #33797 -- Prioritized cached database backend for cached sessions in docs.

Co-authored-by: Adam Johnson <me@adamj.eu>
Backport of fa9ac16c1345a7fb6ad500c84961a954529ba2b9 from main

1 files changed, 18 insertions, 19 deletions

diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt
index 553fb06a61..c6ef6de73f 100644
--- a/docs/topics/http/sessions.txt
+++ b/docs/topics/http/sessions.txt
@@ -72,28 +72,27 @@ If you have multiple caches defined in :setting:`CACHES`, Django will use the
 default cache. To use another cache, set :setting:`SESSION_CACHE_ALIAS` to the
 name of that cache.
 
-Once your cache is configured, you've got two choices for how to store data in
-the cache:
+Once your cache is configured, you have to choose between a database-backed
+cache or a non-persistent cache.
 
-* Set :setting:`SESSION_ENGINE` to
-  ``"django.contrib.sessions.backends.cache"`` for a simple caching session
-  store. Session data will be stored directly in your cache. However, session
-  data may not be persistent: cached data can be evicted if the cache fills
-  up or if the cache server is restarted.
+The cached database backend (``cached_db``) uses a write-through cache --
+session writes are applied to both the cache and the database. Session reads
+use the cache, or the database if the data has been evicted from the cache. To
+use this backend, set :setting:`SESSION_ENGINE` to
+``"django.contrib.sessions.backends.cached_db"``, and follow the configuration
+instructions for the `using database-backed sessions`_.
 
-* For persistent, cached data, set :setting:`SESSION_ENGINE` to
-  ``"django.contrib.sessions.backends.cached_db"``. This uses a
-  write-through cache -- every write to the cache will also be written to
-  the database. Session reads only use the database if the data is not
-  already in the cache.
+The cache backend (``cache``) stores session data only in your cache. This is
+faster because it avoids database persistence, but you will have to consider
+what happens when cache data is evicted. Eviction can occur if the cache fills
+up or the cache server is restarted, and it will mean session data is lost,
+including logging out users. To use this backend, set :setting:`SESSION_ENGINE`
+to ``"django.contrib.sessions.backends.cache"``.
 
-Both session stores are quite fast, but the simple cache is faster because it
-disregards persistence. In most cases, the ``cached_db`` backend will be fast
-enough, but if you need that last bit of performance, and are willing to let
-session data be expunged from time to time, the ``cache`` backend is for you.
-
-If you use the ``cached_db`` session backend, you also need to follow the
-configuration instructions for the `using database-backed sessions`_.
+The cache backend can be made persistent by using a persistent cache, such as
+Redis with appropriate configuration. But unless your cache is definitely
+configured for sufficient persistence, opt for the cached database backend.
+This avoids edge cases caused by unreliable data storage in production.
 
 Using file-based sessions
 -------------------------