fastpluggy-db-purge

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

pip install fastpluggy-db-purge

Configuration

Declaring purge targets from another plugin

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

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:

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