Retention¶
How long calServer keeps records is configured under Administration → General settings → Retention. The period applies to the audit trail and to device data alike.
The two values¶
| Setting | Meaning | Default |
|---|---|---|
| Retention period (years) | When an archived record may be deleted. The allowed range is 10 to 30 years. | 10 |
| Audit trail: hot window (months) | How long an audit entry stays in the table behind the view before it moves to the archive. | 24 |
The two answer different questions. The retention period is a legal requirement and says when something may disappear. The hot window is an operational figure and says where something lives. Moving an entry to the archive deletes nothing.
The minimum period cannot be undercut
A value below 10 years is raised to 10 when read, a value above 30 is capped at 30. This applies not only to the form but to every route into the setting — including an import or a direct write to the database. A period below the minimum retention would not be a saving, it would be a violation.
The hot window is additionally bounded by the retention period. If it reached beyond it, an entry would outlive the period inside the hot table and the deletion run would never see it.
Why there are two stages¶
The audit trail grows with every change. On an actively used installation that amounts to tens of thousands of entries per day; over ten years it becomes hundreds of millions. Holding that volume in the table behind the audit grid makes every query against it slow and every database dump large.
| Stage | Table | Characteristic |
|---|---|---|
| Hot window | audit |
Fully indexed, behind the grid and the detail pages. |
| Archive | audit_archive |
Same columns, fewer indexes, rarely read. |
The cleanup run¶
The scheduled task Archive audit trail (audit:prune) runs daily at 4 a.m.
and works in this order:
- Everything older than the hot window moves to
audit_archive. - Whatever is past the retention period is deleted from the archive.
# Dry run: reports what would move and what would be deleted
docker exec calserver-api-v2 php artisan audit:prune --dry-run
# First run on a grown installation, smaller batches
docker exec calserver-api-v2 php artisan audit:prune --chunk=200
Interrupting is harmless
The run works in batches. If interrupted, the next run picks up where the previous one left off — no half-finished move remains.
What is not included¶
The period is deliberately not stored as an audit-only setting so that a future cleanup run for device data reads the same number. That run does not exist yet: currently only the audit trail enforces the period. Device data is not deleted automatically.