diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index b1ec796ed4..1c1ad0c34b 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 -------------------------