django-db-purge 1.3.0

Django Database Purge

django-db-purge deletes expired database records based on configurable retention policies, run as a scheduled Django management command. It also ships an MCP server so an AI agent can purge records too, safely, behind a preview, token, execute handshake.

Features:

• Flexible Retention Policy: Define your own retention policy to determine which records should be purged from the database.
• Efficient Data Management: Easily manage the size of your database by removing outdated or unnecessary records.
• Customizable: Adapt the command to suit your project's specific requirements and database structure.
• Safe: Built-in safeguards to prevent accidental data loss, ensuring that only the intended records are purged.
• Agent-safe MCP tools: Optionally let an AI agent purge records through a preview, token, execute handshake that blocks deletion without a matching prior preview.
• Row-set bound deletion: A preview binds the exact rows it matched. Execution deletes only those rows, by primary key, and rejects the call outright if the row set drifted in between, so a concurrent write can never widen a purge.

Scheduled purging (cron)

How to Use:

1. Install django-db-purge by running:

pip install django-db-purge

2. Include 'dbpurge' in your INSTALLED_APPS settings.

3. Add a DB_PURGE_RETENTION_POLICIES list to your project's settings.py, based on your requirements. Below is a guide on how to set up the retention policies:

   1. app_name

   • Description: Name of the Django app containing the model.
   • Example: my_django_app

   2. model_name

   • Description: Name of the Django model from which records will be deleted.
   • Example: MyModel

   3. time_based_column_name

   • Description: Name of the column in the model that contains the timestamp or datetime field used for determining the age of records.
   • Example: created_at

   4. data_retention_num_seconds

   • Description: Time duration in seconds for which records will be retained before deletion.
   • Example: 2592000 (for 30 days)

   Example:

   # settings.py
   DB_PURGE_RETENTION_POLICIES = [
       {
           'app_name': 'my_django_app',
           'model_name': 'MyModel',
           'time_based_column_name': 'created_at',
           'data_retention_num_seconds': 2592000,  # 30 days in seconds
       },
       # Add more retention policies as needed
   ]
   

   If DB_PURGE_RETENTION_POLICIES is not set, the command falls back to a placeholder policy that will fail validation until you configure it, so there's no risk of silently deleting the wrong table.

4. Then, either periodically call the db_purge management command (e.g., via a system cronjob), or install and configure django-cron.

MCP server

django-db-purge also ships an MCP server that exposes the same purge logic to an AI agent, with guardrails so an agent can never delete rows without a human-verifiable preview step. It runs inside Django as a management command and speaks the MCP protocol over stdio, so it works with Claude Desktop, the MCP Inspector, or any other MCP-capable host. The server makes no LLM API calls of its own: the host runs the model, and this process only exposes deterministic, schema-validated tools.

Installation

The MCP server needs fastmcp, which is an optional extra, not part of the base install:

pip install "django-db-purge[mcp]"

If fastmcp is not installed, running purge_mcp_server fails immediately with a CommandError pointing back at this install command, rather than a raw import traceback.

Tools

• list_purge_candidates() Read-only. Introspects installed models and returns every app, model, and DateField/DateTimeField column, so an agent can discover valid inputs for the other two tools.

• preview_purge(app_name, model_name, time_column, retention_seconds) Read-only. Validates the policy against live schema, counts matching rows, and returns up to 5 sample rows (primary key and the time column only, never the full row), a confirmation_token, and token_expires_at. Performs no deletion.

• execute_purge(app_name, model_name, time_column, retention_seconds, confirmation_token) Deletes the rows a preview_purge call matched, but only with that call's confirmation_token. Any unknown token, expired token, or parameter mismatch fails with the same "invalid or expired confirmation token" error, so a caller can't distinguish which of those it was. If the matched row set has changed since the preview, the call is rejected outright.

Safety handshake

There is no path to deletion without a prior, matching preview:

1. Call preview_purge to see what would be deleted and get back a confirmation_token.
2. Call execute_purge with that token and the identical parameters, before it expires (5 minutes).

Tokens are single-use: a successful execute_purge consumes the token, so it cannot be replayed. Tokens are also bound to the exact parameter tuple that produced them, so changing any argument invalidates the token even if it hasn't expired. If execute_purge fails for a reason that isn't the caller's fault, such as a row-cap breach or a row-set change below, the token is reinstated so a retry with the same token can still succeed.

A token binds the exact set of rows the preview matched, not just the parameters. execute_purge deletes only those rows, by primary key, so a row that starts matching the retention filter after the preview is never deleted. Before deleting, it re-runs the filter and compares a fingerprint of the matched rows against the preview's; if the row set has changed, the call is rejected with a distinct error naming both row counts, and you need a fresh preview_purge. The fingerprint covers primary keys only by default, so a row that is modified but still matches is still deleted. Set DB_PURGE_MCP_FINGERPRINT_FIELDS to include specific column values in it and reject in-place modifications too. See DESIGN.md for the full rationale, including the cascade limitation.

Settings

• DB_PURGE_MCP_ALLOWED_MODELS List of models that may be purged via MCP, in "app_label.ModelName" format (e.g. ["tests.SampleRecord"]). Matched case-insensitively, so "tests.samplerecord" also works. Defaults to an empty list, meaning nothing is purgeable until you configure it. Enforced on both preview_purge and execute_purge.

• DB_PURGE_MCP_MAX_ROWS Maximum number of matching rows an execute_purge call may delete, re-checked at execute time even if the preview was under the cap. Defaults to 10000. This bounds the rows matched by time_column, not cascade fan-out: ON DELETE CASCADE relations can remove additional related rows beyond this cap. It also bounds the size of the row-set fingerprint a preview stores.

• DB_PURGE_MCP_FINGERPRINT_FIELDS Optional, per model, opt-in. Maps a model label to the extra columns to include in that model's row-set fingerprint, e.g. {"tests.SampleRecord": ["label"]}. Model labels are matched case-insensitively, like DB_PURGE_MCP_ALLOWED_MODELS. Defaults to an empty dict, meaning fingerprints cover primary keys only, so rows modified in place between preview and execute are still deleted as long as they still match the filter. Name columns here to have execute_purge reject those modifications as well. There is no assumption that a model has an updated_at or version column: configure whichever columns matter to you.

Running the server

Inside your project's virtualenv, with dbpurge in INSTALLED_APPS:

python manage.py purge_mcp_server

This boots Django (settings, ORM, app registry) and then serves the three tools above over stdio.

Claude Desktop configuration

Add an entry to Claude Desktop's claude_desktop_config.json, pointing at your project's virtualenv Python and manage.py:

{
  "mcpServers": {
    "django-db-purge": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["/path/to/your/project/manage.py", "purge_mcp_server"],
      "cwd": "/path/to/your/project"
    }
  }
}

Use the venv's Python directly (not a bare python), since fastmcp and your project's dependencies need to be importable.

Inspecting the server

To poke at the tools interactively, run the server through the MCP Inspector:

npx @modelcontextprotocol/inspector python manage.py purge_mcp_server

Run this from inside your project's virtualenv (activated, or with that venv's python on PATH), so the python the Inspector spawns is the one with Django and fastmcp installed.

A healthy tools/list response shows all three tools: list_purge_candidates, preview_purge, and execute_purge, each with a JSON schema derived from its type hints.

Running the tests

From a bare checkout, with this package installed with the mcp extra (pip install -e ".[mcp]"), no separate install step for Django or fastmcp is required:

python runtests.py

This runs the full Django test suite, including token lifecycle, allowlist, and row-cap coverage, against an in-memory sqlite database.

To exercise the server the way a real MCP client would, over an actual stdio subprocess:

python tests/e2e_stdio.py

This seeds a temporary sqlite database, spawns python -m django purge_mcp_server, and drives a full preview, execute, and reuse-rejected round trip over JSON-RPC.

Contributions:

Contributions are welcome! If you encounter any issues or have suggestions for improvements, please submit an issue or pull request on GitHub.

License:

This project is licensed under the MIT License.