feat(tables): add automatic row expiration with TTL

[j15z]

Summary

Tables can now expire rows automatically with one Expiration column. Cells use the date editor, APIs and workflows store integer Unix epoch seconds, and a bounded cleanup job removes eligible rows every fifteen minutes.

This is PR 2 of 4 in the row-expiration stack. It builds on the generic registry hooks in PR #7119; PR #7072 supplies the safety-critical timezone consolidation; PR #7161 lets deletions trigger workflows.

The global table-row-ttl runtime feature flag gates UI availability, schema mutations, and cleanup dispatch. Outside AppConfig, the TABLE_ROW_TTL secret is the global on/off fallback.

Cleanup is round-robin across candidate tables and is capped at 100 batches of 500 rows per run. Each table is scanned by created_at and id so older rows cannot starve, but only the Expiration value decides whether a row is deleted. The supporting database index matches that scan order.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Other: ___________

Testing

• 55 focused tests pass for the feature flag, server-side availability guards, schema limits, cleanup behavior, cron dispatch, and column pickers.
• Cleanup coverage verifies batching and fairness while future, empty, and malformed Expiration values remain untouched.
• The cron route coverage verifies authentication, fifteen-minute deduplication, feature-disabled behavior, and async-job dispatch.
• bun run type-check, lint, all 33 repository audits, the block-registry check, and the docs-manifest check pass at the stack tip.
• bun run check:migrations origin/staging passes. A local migration apply could not run because no local PostgreSQL server was available.
• Review focus: deletion eligibility must depend only on the stored Expiration epoch; a row may be removed late, but never early.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

No screenshots captured. Component tests cover the Expiration picker, its one-column limit, disabled-state explanation, and cell rendering.

---

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 28, 2026 10:57pm

[greptile-apps]

Greptile Summary

This PR adds a TTL table-column type backed by Unix epoch seconds, including validation, timezone-aware editing, import and conversion support, and documentation.

• Adds scheduled, serialized background cleanup of expired table rows.
• Enforces one TTL column per table across schema validation and table mutation flows.
• Adds TTL rendering, editing, picker availability, tests, deployment schedules, and generated tool metadata.

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking cleanup-fairness issue that can leave later tables behind under sustained high-volume expiration workloads.

The TTL representation and mutation paths are internally consistent, but the cleanup worker's fixed ordering and shared batch budget allow an early table to repeatedly monopolize scheduled cleanup capacity.

Files Needing Attention: apps/sim/background/cleanup-table-row-ttl.ts

Important Files Changed

Filename	Overview
apps/sim/background/cleanup-table-row-ttl.ts	Implements locked, batched TTL deletion; the global budget and fixed table ordering can create unbounded lag under sustained backlog.
apps/sim/lib/table/column-types/ttl.ts	Defines TTL epoch-second coercion, validation, conversion, and timezone-aware formatting.
apps/sim/lib/table/columns/service.ts	Applies source-aware value conversion and validates the resulting schema before retyping columns.
apps/sim/lib/table/schema-invariants.ts	Extends shared schema invariants with registry-declared per-table column limits.
apps/sim/app/api/cron/cleanup-table-row-ttl/route.ts	Adds an authenticated cron endpoint that dispatches one deduplicated, serialized cleanup job.
apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/cells/inline-editors.tsx	Normalizes date-editor saves through timezone-aware column coercion so TTL cells persist epoch seconds.
helm/sim/values.yaml	Enables the TTL cleanup endpoint on a five-minute non-overlapping cron schedule.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Cron[Five-minute cron] --> Route[Authenticated cleanup route]
  Route --> Queue[Serialized cleanup job]
  Queue --> List[List tables with expired TTL rows]
  List --> Lock[Acquire table advisory lock]
  Lock --> Batch[Delete up to 500 expired rows]
  Batch -->|More rows and budget remains| Lock
  Batch -->|Table complete| Signal[Signal table rows changed]
  Signal -->|More tables and budget remains| Lock

Loading

_{Reviews (1): Last reviewed commit: "feat(tables): add row TTL expiration" | Re-trigger Greptile}

[cubic-dev-ai]

Review completed against the latest diff

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>