Data Retention
What the kit deletes on its own, when, and how to add retention for your tables: cleanup tasks for old rows, purge targets for rows a deleted user or organization leaves behind.
Rows that nobody needs any more are deleted in the background, in small batches, as outbox jobs. Two kinds of work do it:
- Cleanup tasks delete rows past a retention window, once a day: expired sessions, old exports, finished invitations.
- Purges delete everything a deleted user or organization owned in tables too big to cascade: events, logs, messages.
Both only ever delete, one bounded batch per transaction (1000 rows by default), so a backlog of millions never turns into one long lock.
What the Kit Deletes
Every day at 03:00 UTC (apps/web/crons/cleanup.ts), the kit's tasks run:
| Task | Deletes | Keeps |
|---|---|---|
kit.sessions | Sessions expired over a day ago | Live sessions |
kit.verifications | Email and reset tokens expired over a day ago | Unexpired tokens |
kit.step-up | Step-up codes expired over a day ago | Codes the hourly and daily limits still count |
kit.rate-limits | Rate-limit counters idle over a day | Counters inside any rate-limit window |
kit.invitations | Accepted, canceled, rejected and expired invitations, 30 days after they were sent | Pending invitations that haven't expired, whatever their age |
Retention is your responsibility: if you must keep these longer (an audit duty), lengthen or turn off any of them in apps/web/config/cleanup.config.server.ts (Cleanup Tasks).
Which One Do I Need?
| Your data | Use |
|---|---|
| Rows that become useless after a while (exports, temporary uploads, old notifications) | A cleanup task |
| A table that grows without bound per user or organization (events, logs, messages, audit rows) | A purge target: indexed owner id, no foreign key, purged after the owner is deleted |
| A child table with a handful of rows per parent (memberships, settings, projects) | onDelete: 'cascade' (Your Tables) |
| Anything outside your database (files in storage, a record in another system) | An after-delete hook, or for a deleted account an exit hook |
Cascade or Purge Target?
A cascade deletes every child row in the same transaction as the parent. That is fine for a few rows and a problem for millions: the delete holds locks that block migrations and writes, and floods the database with WAL and dead rows. A purge target moves that work to the background, in batches.
A table can be both: an events table kept 90 days is a cleanup task (old rows) and a purge target (a deleted organization's rows).
Where Things Live
| File | Owner | What |
|---|---|---|
apps/web/config/cleanup.config.server.ts | You | Changes to the kit's tasks, your tasks, your purge targets |
apps/web/config/account-hooks.config.server.ts | You | What happens when a user deletes their account: policies, steps, after-hooks (Exit Hooks) |
apps/web/config/cleanup.server.ts | Kit | Binds the engine to the database and the kit's tables |
apps/web/crons/cleanup.ts | Kit | The daily schedule (0 3 * * *); change the time here |
apps/web/lib/cleanup.server.ts | Kit | Saves organization purge jobs before Better Auth's delete; requestPurge serves delete code you write |
The engine is @kit/cleanup. Its jobs, cleanup.task and cleanup.purge, run on the outbox like any other job: retried, visible in outbox.job, replayable (Running and Failures).
What Gets Logged
Task and target names, counts, durations and ids. Never the rows' contents. Fields are nested under cleanup (tasks) or purge (purges), so filter Workers Logs on those:
cleanup scheduled:{ day, created, existing, disabled }, once per daily run.cleanup task finished/cleanup task continues:{ task, day, step, deleted, batches, durationMs }.purge continues,purge drained, final pass scheduled,purge finished:{ ownerKind, ownerId, step, finalPass, deleted, failed, durationMs };purge retries(warn) andpurge target failed(error, with the target) when a target fails.
Next: Cleanup Tasks →