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:

TaskDeletesKeeps
kit.sessionsSessions expired over a day agoLive sessions
kit.verificationsEmail and reset tokens expired over a day agoUnexpired tokens
kit.step-upStep-up codes expired over a day agoCodes the hourly and daily limits still count
kit.rate-limitsRate-limit counters idle over a dayCounters inside any rate-limit window
kit.invitationsAccepted, canceled, rejected and expired invitations, 30 days after they were sentPending 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 dataUse
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

FileOwnerWhat
apps/web/config/cleanup.config.server.tsYouChanges to the kit's tasks, your tasks, your purge targets
apps/web/config/account-hooks.config.server.tsYouWhat happens when a user deletes their account: policies, steps, after-hooks (Exit Hooks)
apps/web/config/cleanup.server.tsKitBinds the engine to the database and the kit's tables
apps/web/crons/cleanup.tsKitThe daily schedule (0 3 * * *); change the time here
apps/web/lib/cleanup.server.tsKitSaves 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) and purge target failed (error, with the target) when a target fails.

Next: Cleanup Tasks →