Metadata-Version: 2.4
Name: django-db-purge
Version: 1.2.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.

## 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 matching rows, but only with a `confirmation_token` from a matching `preview_purge` call. 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.

### 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 below, the token is reinstated so a retry with the same token can still succeed.

### 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.

### 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.

---
