Skip to main content
Administration → Data Retention → /data-retention Some tables grow forever. Delivery logs, webhook events, poll failures, meter readings and audit streams accumulate at a rate set by the size of the portfolio, not by anything a user does. Data retention is the engine that ages those rows out on a policy, so storage stays bounded and queries stay fast. It is deliberately hard to arm. Two surfaces:

​
The safety model

An armed retention policy deletes production rows in bulk and the rows do not come back. Arming requires three separate switches to line up:
  1. RETENTION_SWEEPER_ENABLED — the environment-level master switch for the sweeper.
  2. RETENTION_ARMED — the environment-level arm switch.
  3. The per-policy is_armed column.
All three must be on before a single row is removed. Any one of them off means the sweep runs in shadow mode: it computes exactly what it would delete, records the counts, and deletes nothing.
There is no arm/disarm button in the app, and this is intentional. Policies are authored and armed by migration or explicit SQL, where the change leaves a reviewable trail. A browser toggle would collapse a three-switch safety model into one click.

​
Reading a policy

Blank columns exists for tables where the row itself is still needed — a record of the event — but the payload inside it is not. It shrinks the table without breaking references.

​
Reading a run

Each sweep produces a run record per policy. A refused run is not a failure. It means a guard fired — the policy was misconfigured, the scope was implausibly large, or a switch was off — and the engine declined rather than guessing.

​
Bringing a policy into service

1

Author it in shadow

The policy is created disarmed. Nothing is deleted.
2

Let it sweep and read the runs

Check rows in scope against what you expect. A count far larger than anticipated usually means the wrong date column or a missing filter.
3

Check the cutoff date

Confirm the cutoff lands where the keep-days value implies.
4

Confirm the data is genuinely disposable

Check nothing reports off it, and that any regulatory retention period is longer than the keep-days value, not shorter.
5

Arm deliberately

By migration, with the shadow evidence in the change description.
6

Watch the first armed runs

Expect a backlog over several sweeps rather than one large deletion.
Deleting rows does not immediately return disk to the operating system — the space is reused by the table before the file shrinks. Table size on disk will plateau before it falls.

​
Common problems

Scheduled tasks

The sweeper’s cadence and run history.

Activity log

What the audit trail retains, and for how long.

Platform health

Detecting data problems before they age out.

Admin console

Platform-wide operational streams.