Metadata-Version: 2.4
Name: fastpluggy-db-purge
Version: 1.0.2
Summary: Centralized database retention management and purge plugin for FastPluggy
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: FastPluggy>=0.4.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: tests
Requires-Dist: pytest>=7.0; extra == "tests"
Requires-Dist: pytest-cov>=4.0; extra == "tests"
Requires-Dist: psycopg2-binary>=2.9; extra == "tests"
Provides-Extra: e2e
Requires-Dist: fastpluggy-cli; extra == "e2e"
Requires-Dist: playwright>=1.40.0; extra == "e2e"

# fastpluggy-db-purge

![DB Purge](https://img.shields.io/badge/FastPluggy-DB%20Purge-blue)
[![Release](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/db_purge/-/badges/release.svg)](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/db_purge/-/releases)
[![Pipeline Status](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/db_purge/badges/main/pipeline.svg?key_text=CI)](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/db_purge/-/pipelines?ignore_skipped=true)
[![Coverage](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/db_purge/badges/main/coverage.svg)](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/db_purge/-/pipelines)

Centralized database retention management and purge plugin for FastPluggy.

## Features

- Auto-discover all database tables with row counts and sizes
- Per-table retention policies via admin UI
- Plugin-declared purge targets via `fp_purge_targets` hook — declaring a
  table upserts a **disabled** rule an admin enables to validate (see below)
- Manual and scheduled purge with batched deletes
- Full audit trail of purge operations

## Installation

```bash
pip install fastpluggy-db-purge
```

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| `default_retention_days` | 30 | Global fallback retention |
| `batch_size` | 5000 | Rows per DELETE batch |
| `dry_run_by_default` | True | Safety default for manual purges |
| `auto_purge_enabled` | False | Enable scheduled purge |
| `auto_purge_cron` | `0 4 * * *` | Cron schedule (daily 4am UTC) |

## Declaring purge targets from another plugin

A plugin can declare its own tables as purgeable from its `on_load_complete()`:

```python
from fastpluggy_plugin.db_purge.hooks import register_purge_target

register_purge_target("task_reports", "end_time", default_retention_days=30)
```

This does two things:

1. Registers the table + declared defaults in the in-memory registry, so it
   shows on the DB Purge dashboard (marked *declared by plugin*).
2. Upserts a persistent rule in `fp_purge_rules`, created **disabled**. An admin
   must enable it in the web UI before anything is deleted — a validation gate,
   so declaring a table can never silently purge its data.

If the plugin later changes what it declares (timestamp column or retention),
the rule is refreshed and **re-disabled** for the admin to re-validate.
Provenance is tracked by a `declared_hash` column: plugin-managed rows carry the
hash; admin-created rows have `declared_hash = NULL` and are never touched by the
hook.

To exclude a config/system table from purge entirely:

```python
from fastpluggy_plugin.db_purge.hooks import register_purge_excluded

register_purge_excluded("my_plugin_config")
```

> **Schema note (v1.0.0):** `fp_purge_rules` gained a `declared_hash` column.
> Existing installs are migrated automatically on load via a guarded
> `ALTER TABLE ... ADD COLUMN` (idempotent; SQLite + PostgreSQL).
