Add store that uses cache framework

Use functools.wraps() in _UntrackedCache

Use delete_many for efficiency

Use deque for O(1) pops

Add test to verify no self cache tracking

Refactor tests with a `CommonStoreTestsMixin`

Add tests for different cache backends

Author: robhudson

debug_toolbar/settings.py

@@ -18,6 +18,8 @@ def _is_running_tests():
 
 CONFIG_DEFAULTS = {
     # Toolbar options
+    "CACHE_BACKEND": "default",
+    "CACHE_KEY_PREFIX": "djdt:",
     "DISABLE_PANELS": {
         "debug_toolbar.panels.profiling.ProfilingPanel",
         "debug_toolbar.panels.redirects.RedirectsPanel",

debug_toolbar/store.py

@@ -1,9 +1,11 @@
 import contextlib
+import functools
 import json
 from collections import defaultdict, deque
 from collections.abc import Iterable
 from typing import Any
 
+from django.core.cache import caches
 from django.core.serializers.json import DjangoJSONEncoder
 from django.db import transaction
 from django.utils.module_loading import import_string
@@ -219,5 +221,175 @@ def panels(cls, request_id: str) -> Any:
             return {}
 
 
+class _UntrackedCache:
+    """
+    Wrapper around a Django cache backend that suppresses debug toolbar tracking.
+
+    The cache panel's monkey-patched methods check ``cache._djdt_panel`` and skip
+    recording when it is ``None``.  This proxy temporarily sets that attribute to
+    ``None`` around every call so the toolbar's own cache operations are invisible.
+    """
+
+    def __init__(self, cache):
+        self._cache = cache
+
+    def __getattr__(self, name):
+        attr = getattr(self._cache, name)
+        if not callable(attr):
+            return attr
+
+        @functools.wraps(attr)
+        def untracked(*args, **kwargs):
+            panel = getattr(self._cache, "_djdt_panel", None)
+            self._cache._djdt_panel = None
+            try:
+                return attr(*args, **kwargs)
+            finally:
+                self._cache._djdt_panel = panel
+
+        return untracked
+
+
+class CacheStore(BaseStore):
+    """
+    Store that uses Django's cache framework to persist debug toolbar data.
+    """
+
+    _cache_table_registered = False
+
+    @classmethod
+    def _get_cache(cls):
+        """Get the Django cache backend, wrapped to bypass toolbar tracking."""
+        cache = _UntrackedCache(caches[dt_settings.get_config()["CACHE_BACKEND"]])
+
+        # Register the cache table with DDT_MODELS to filter SQL queries
+        if not cls._cache_table_registered:
+            cls._register_cache_table_for_sql_filtering(cache._cache)
+            cls._cache_table_registered = True
+
+        return cache
+
+    @classmethod
+    def _register_cache_table_for_sql_filtering(cls, cache):
+        """
+        Add the cache table to DDT_MODELS.
+
+        This ensures that when using DatabaseCache, the cache table's SQL queries
+        don't appear in the SQLPanel.
+        """
+        # Only proceed if this is a DatabaseCache backend
+        if cache.__class__.__name__ != "DatabaseCache":
+            return
+
+        # Get the cache table name
+        cache_table = getattr(cache, "_table", None)
+        if cache_table:
+            # Import here to avoid circular dependency:
+            # store.py -> panels/sql/tracking.py -> panels/sql/forms.py -> toolbar.py -> store.py
+            from debug_toolbar.panels.sql import tracking
+
+            tracking.DDT_MODELS.add(cache_table)
+
+    @classmethod
+    def _key_prefix(cls) -> str:
+        """Get the cache key prefix from settings."""
+        return dt_settings.get_config()["CACHE_KEY_PREFIX"]
+
+    @classmethod
+    def _request_ids_key(cls) -> str:
+        """Return the cache key for the request IDs list."""
+        return f"{cls._key_prefix()}request_ids"
+
+    @classmethod
+    def _request_key(cls, request_id: str) -> str:
+        """Return the cache key for a specific request's data."""
+        return f"{cls._key_prefix()}req:{request_id}"
+
+    @classmethod
+    def request_ids(cls) -> Iterable:
+        """The stored request ids."""
+        return cls._get_cache().get(cls._request_ids_key(), [])
+
+    @classmethod
+    def exists(cls, request_id: str) -> bool:
+        """Does the given request_id exist in the store."""
+        return request_id in cls.request_ids()
+
+    @classmethod
+    def set(cls, request_id: str):
+        """Set a request_id in the store."""
+        cache = cls._get_cache()
+        ids_key = cls._request_ids_key()
+        request_ids = deque(cache.get(ids_key, []))
+
+        if request_id not in request_ids:
+            request_ids.append(request_id)
+
+        # Enforce RESULTS_CACHE_SIZE limit
+        max_size = dt_settings.get_config()["RESULTS_CACHE_SIZE"]
+        while len(request_ids) > max_size:
+            removed_id = request_ids.popleft()
+            cache.delete(cls._request_key(removed_id))
+
+        cache.set(ids_key, list(request_ids), None)
+
+    @classmethod
+    def clear(cls):
+        """Remove all requests from the request store."""
+        cache = cls._get_cache()
+        ids_key = cls._request_ids_key()
+        request_ids = cache.get(ids_key, [])
+
+        # Delete all request data
+        if request_ids:
+            cache.delete_many([cls._request_key(_id) for _id in request_ids])
+
+        # Clear the request IDs list
+        cache.delete(ids_key)
+
+    @classmethod
+    def delete(cls, request_id: str):
+        """Delete the stored request for the given request_id."""
+        cache = cls._get_cache()
+        ids_key = cls._request_ids_key()
+        request_ids = list(cache.get(ids_key, []))
+
+        # Remove from the list if present
+        if request_id in request_ids:
+            request_ids.remove(request_id)
+            cache.set(ids_key, request_ids, None)
+
+        # Delete the request data
+        cache.delete(cls._request_key(request_id))
+
+    @classmethod
+    def save_panel(cls, request_id: str, panel_id: str, data: Any = None):
+        """Save the panel data for the given request_id."""
+        cls.set(request_id)
+        cache = cls._get_cache()
+        request_key = cls._request_key(request_id)
+        request_data = cache.get(request_key, {})
+        request_data[panel_id] = serialize(data)
+        cache.set(request_key, request_data, None)
+
+    @classmethod
+    def panel(cls, request_id: str, panel_id: str) -> Any:
+        """Fetch the panel data for the given request_id."""
+        cache = cls._get_cache()
+        request_data = cache.get(cls._request_key(request_id), {})
+        panel_data = request_data.get(panel_id)
+        if panel_data is None:
+            return {}
+        return deserialize(panel_data)
+
+    @classmethod
+    def panels(cls, request_id: str) -> Any:
+        """Fetch all the panel data for the given request_id."""
+        cache = cls._get_cache()
+        request_data = cache.get(cls._request_key(request_id), {})
+        for panel_id, panel_data in request_data.items():
+            yield panel_id, deserialize(panel_data)
+
+
 def get_store() -> BaseStore:
     return import_string(dt_settings.get_config()["TOOLBAR_STORE_CLASS"])

docs/architecture.rst

@@ -68,9 +68,13 @@ the store ID. This is so that the toolbar can load the collected metrics
 for that particular request.
 
 The history panel allows a user to view the metrics for any request since
-the application was started. The toolbar maintains its state entirely in
-memory for the process running ``runserver``. If the application is
-restarted the toolbar will lose its state.
+the application was started. By default, the toolbar maintains its state
+entirely in memory (``MemoryStore``) for the process running ``runserver``.
+If the application is restarted the toolbar will lose its state. To persist
+data across restarts, configure ``TOOLBAR_STORE_CLASS`` to use
+``DatabaseStore`` or ``CacheStore``. See the
+:ref:`TOOLBAR_STORE_CLASS <TOOLBAR_STORE_CLASS>` configuration option for
+details.
 
 Problematic Parts
 -----------------

docs/changes.rst

@@ -18,6 +18,12 @@ Pending
   ensure the latest static assets are used.
 * Fixed bug with ``CachePanel`` so the cache patching is only applied
   once.
+* Added ``debug_toolbar.store.CacheStore`` for storing toolbar data using
+  Django's cache framework. This provides persistence without requiring
+  database migrations, and works with any cache backend (Memcached, Redis,
+  database, file-based, etc.).
+* Added ``CACHE_BACKEND`` and ``CACHE_KEY_PREFIX`` settings to configure the
+  ``CacheStore``.
 
 6.2.0 (2026-01-20)
 ------------------

docs/configuration.rst

@@ -53,6 +53,43 @@ toolbar itself, others are specific to some panels.
 Toolbar options
 ~~~~~~~~~~~~~~~
 
+* ``CACHE_BACKEND``
+
+  Default: ``"default"``
+
+  The alias of the Django cache backend to use when
+  :ref:`TOOLBAR_STORE_CLASS <TOOLBAR_STORE_CLASS>` is set to
+  ``debug_toolbar.store.CacheStore``. This should match one of the keys in
+  your :setting:`CACHES` setting.
+
+  Using a dedicated cache backend for the toolbar is recommended in
+  production-like environments to avoid evicting application cache entries:
+
+  .. code-block:: python
+
+      CACHES = {
+          "default": {
+              "BACKEND": "django.core.cache.backends.redis.RedisCache",
+              "LOCATION": "redis://127.0.0.1:6379",
+          },
+          "debug-toolbar": {
+              "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+          },
+      }
+
+      DEBUG_TOOLBAR_CONFIG = {
+          "TOOLBAR_STORE_CLASS": "debug_toolbar.store.CacheStore",
+          "CACHE_BACKEND": "debug-toolbar",
+      }
+
+* ``CACHE_KEY_PREFIX``
+
+  Default: ``"djdt:"``
+
+  A prefix applied to all cache keys used by the ``CacheStore``. This
+  prevents collisions with other cache entries when sharing a cache
+  backend with the rest of your application.
+
 * ``DISABLE_PANELS``
 
   Default:
@@ -190,22 +227,30 @@ Toolbar options
 
   Available store classes:
 
-  * ``debug_toolbar.store.MemoryStore`` - Stores data in memory
-  * ``debug_toolbar.store.DatabaseStore`` - Stores data in the database
-
-  The DatabaseStore provides persistence and automatically cleans up old
-  entries based on the ``RESULTS_CACHE_SIZE`` setting.
-
-  Note: When using ``DatabaseStore`` migrations are required for
+  * ``debug_toolbar.store.MemoryStore`` - Stores data in memory. This is the
+    default and requires no additional configuration. Data is lost when the
+    server restarts.
+  * ``debug_toolbar.store.DatabaseStore`` - Stores data in the database.
+    Requires running migrations (see below).
+  * ``debug_toolbar.store.CacheStore`` - Stores data using Django's cache
+    framework. Works with any cache backend (Memcached, Redis, database,
+    file-based, etc.). See ``CACHE_BACKEND`` and ``CACHE_KEY_PREFIX`` below
+    for configuration options.
+
+  The ``DatabaseStore`` and ``CacheStore`` both provide persistence across
+  server restarts and automatically clean up old entries based on the
+  ``RESULTS_CACHE_SIZE`` setting.
+
+  Note: When using ``DatabaseStore``, migrations are required for
   the ``debug_toolbar`` app:
 
   .. code-block:: bash
 
       python manage.py migrate debug_toolbar
 
-  For the ``DatabaseStore`` to work properly, you need to run migrations for the
-  ``debug_toolbar`` app. The migrations create the necessary database table to store
-  toolbar data.
+  The toolbar's own cache and SQL operations are automatically hidden from
+  the cache and SQL panels when using ``CacheStore``, so you won't see the
+  toolbar's internal bookkeeping in the collected metrics.
 
 .. _TOOLBAR_LANGUAGE:
 
@@ -418,12 +463,20 @@ Here's what a slightly customized toolbar configuration might look like::
         'SQL_WARNING_THRESHOLD': 100,   # milliseconds
     }
 
-Here's an example of using a persistent store to keep debug data between server
+Here's an example of using the database store to keep debug data between server
 restarts::
 
     DEBUG_TOOLBAR_CONFIG = {
-        'TOOLBAR_STORE_CLASS': 'debug_toolbar.store.DatabaseStore',
-        'RESULTS_CACHE_SIZE': 100,  # Store up to 100 requests
+        "TOOLBAR_STORE_CLASS": "debug_toolbar.store.DatabaseStore",
+        "RESULTS_CACHE_SIZE": 100,  # Store up to 100 requests
+    }
+
+Here's an example of using the cache store, which provides persistence without
+requiring migrations::
+
+    DEBUG_TOOLBAR_CONFIG = {
+        "TOOLBAR_STORE_CLASS": "debug_toolbar.store.CacheStore",
+        "CACHE_BACKEND": "default",  # Or a dedicated cache alias
     }
 
 Theming support