Start with a retention contract
Retention is a product policy implemented across several systems, not a nightly DELETE query. Identify each record class, the business reason to keep it, the event that starts its retention clock, and the owner who can approve a change. Treat operational records, customer uploads, analytics, and security logs as separate categories.
Define timestamps such as expires_at explicitly. A record created a year ago may still belong to an active contract, while a temporary export generated yesterday may already be eligible for removal. Policy should explain whether an edit resets the clock; do not infer that from a generic updated_at column. This engineering guide does not prescribe legal retention periods.
Preview an immutable, scoped candidate manifest
Separate identifying candidates from deleting them. Create a purge-run record containing tenant scope, record category, cutoff time, policy revision, dry-run counts, and operator or scheduled-job identity. Use a stable cutoff for the whole run so a long execution does not continually expand its target.
Capture IDs and relevant record revisions in a manifest, or use a reproducible bounded query with a durable cursor when materializing every ID is impractical. Before approval, show estimated database rows, object-storage bytes, and downstream dependencies. A tenant-facing administrator must never be able to approve another tenant’s deletion through an unvalidated filter.
Recheck eligibility at the destructive boundary
A preview is not authority to erase a record regardless of later changes. Immediately before mutation, recheck tenant, current state, retention deadline, holds, and revision where needed. A record placed on hold after the preview must not disappear when an old manifest is executed.
Make the guard and state transition atomic using the facilities appropriate to your database. One useful lifecycle is eligible, pending purge, purging, and completed, with held and failed outcomes tracked independently. If a record becomes ineligible, skip it with a reason instead of silently weakening the policy.
Run bounded batches with durable checkpoints
Keep the Next.js request responsible for authorization and durable acceptance, not an unbounded purge loop. Execute work in a worker with explicit concurrency, batch size, time budget, and retry limits. Persist progress after completed units, and make each unit safe to replay after a crash.
Prefer a stable key cursor over offset pagination on a shrinking result set. Limit each transaction so database locks, replication delay, and application latency remain observable. A pause control should stop dispatching new batches; it cannot undo a deletion already committed. Report scanned, deleted, skipped, and failed counts separately.
Coordinate database rows, files, and downstream copies
Deleting the parent row first can discard the only pointer to a stored object. Persist cleanup intent with the authoritative state change, for example through a transactional outbox. Give every storage deletion and downstream notification an idempotent identity so retries converge without needing exactly-once delivery.
Track derived copies such as thumbnails, search entries, cached exports, and analytics projections. Enforce access denial as soon as the authoritative record enters the appropriate deleted state; eventual physical cleanup must not leave a public download usable indefinitely. Verify object versioning and lifecycle settings rather than assuming that deleting a key erases every prior version.
Distinguish soft deletion, grace periods, and actual erasure
A soft-deleted flag provides a recovery workflow but leaves data stored. If the product offers a grace period, define who may restore, what happens to relationships, and whether restoration cancels pending cleanup. After irreversible purge begins, do not offer a restore button that merely recreates an empty database row.
Backups have their own lifecycle. Document when historical copies age out and restrict who can restore them. Keep a suitably minimized deletion ledger so a recovery exercise can reapply deletions that occurred after the backup snapshot. Do not retain the original sensitive payload in that ledger or claim immediate deletion from every backup without verifying it.
Expose useful status without retaining deleted content
Record policy version, safe record identifiers, run scope, actor, timestamps, and outcome. Avoid copying full customer records into audit logs or dead-letter payloads simply to diagnose a purge failure. Retention must cover operational diagnostics too, with separately justified access and expiry.
Alert on oldest pending cleanup age, repeated authorization failures, unexplained candidate spikes, stalled batches, and differences between expected and completed object removals. Give support staff a scoped run screen showing what was skipped and why, plus a controlled retry action. A successful job status should mean its defined work finished, not that every external service has acknowledged erasure.
Test the irreversible edge cases before enabling the schedule
Exercise a hold added after preview, tenant suspension, a policy revision during execution, duplicate delivery, a worker crash after storage deletion but before checkpoint, and a restore from a snapshot that predates a deletion. Verify authorization using two tenants with similar-looking records.
Roll out with dry runs, representative sampled review, conservative batches, and a kill switch. Test the restore procedure in an isolated environment with controlled data. Start the schedule only after the team understands its maximum deletion volume, error recovery, and escalation ownership. A retention feature is complete when both deletion and exceptional recovery are understandable.
Build a more dependable Next.js application
Endurance Softwares helps teams design, build, test, and operate production-ready Next.js platforms.