Metadata-Version: 2.4
Name: django-db-purge
Version: 1.3.0
Summary: Clean up your Django database effortlessly with customizable record removal based on your retention policy
Home-page: https://github.com/topunix/django-db-purge
Author: topunix
Author-email: topunixguy@gmail.com
License: MIT
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=2
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.0; extra == "mcp"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

---

## 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:
```bash
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:

    ```python
    # 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:

```bash
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](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`:

```bash
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`:

```json
{
  "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:

```bash
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:

```bash
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:

```bash
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.

---
