Fixed #32785 -- Optimized cull frequency for DBCache.

1 files changed, 18 insertions, 1 deletions

diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 9af28a9324..587a91859e 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -254,7 +254,16 @@ In this example, the cache table's name is ``my_cache_table``::
 
 Unlike other cache backends, the database cache does not support automatic
 culling of expired entries at the database level. Instead, expired cache
-entries are culled each time ``add()``, ``set()``, or ``touch()`` is called.
+entries are culled when an ``add()``, ``set()``, or ``touch()`` is called.
+
+Since the cull operation can be expensive for a large cache, you may control
+how often this check occurs by setting ``CULL_PROBABILITY`` to a value between
+0 and 1. This makes the cull probabilistic, occurring on that percentage of
+writes. The default is ``0.1`` (10%).
+
+.. versionadded:: 6.2
+
+    The ``CULL_PROBABILITY`` option was added.
 
 .. _database-caching-creating-the-table:
 
@@ -499,6 +508,14 @@ 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.
 
+  * ``CULL_PROBABILITY``: The percentage of writes that will trigger a cull on
+    the database backend. This value should be between 0 and 1: the default is
+    ``0.1``.
+
+  .. versionadded:: 6.2
+
+    The ``CULL_PROBABILITY`` option was added.
+
   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.