Cross-posted from the Centrali blog. The canonical version with code highlighting and updates lives there.

TL;DR: Record TTL (time-to-live) is a database feature that automatically deletes records once they expire. You set an expiration time on a record — by duration ("delete in 1 hour") or by timestamp ("delete on March 1") — and the database removes it without a cron job. This is database TTL; it's the same idea as DNS TTL but applied to rows in a table instead of cached DNS lookups.

A note before we go further: if you searched for "TTL" and ended up here looking for DNS TTL (how long a DNS resolver caches an A/AAAA/CNAME record), this isn't that post — try Cloudflare's DNS TTL reference. This post is about record TTL in databases: making rows in your data store auto-delete on a schedule.

What Is Record TTL?

Record TTL is a per-record expiration time. The database tracks an expiresAt timestamp on the record (either set explicitly or computed from a duration), and once that timestamp passes:

1. The record disappears from query results immediately (read-time filtering).
2. A background sweep deletes it from storage permanently.

The two writes you make as a developer are:

• ttlSeconds — a duration. "Delete this record 3,600 seconds from now." The database calculates the absolute expiresAt for you.
• expiresAt — an absolute timestamp. "Delete this record at 2026-09-01T00:00:00Z."

Both end up storing the same field. Use ttlSeconds when the deadline is relative ("expire 24 hours after creation"); use expiresAt when the deadline is fixed ("expire on the sale end date").

How TTL Works (Mechanically)

Three things happen between "you wrote a TTL" and "the record is gone":

1. Write time — you create or update a record with ttlSeconds or expiresAt. The database stores the absolute expiration timestamp on the record.
2. Read time — every query is implicitly filtered against now(). Records past their expiresAt are excluded from results, even if they haven't been physically deleted yet.
3. Sweep time — a background job (every few minutes, depending on the database) finds expired records and deletes them. Some systems also publish an event ("record.expired") so your app can react before the row is gone.

The key property: expired records become invisible to your application instantly, even if the on-disk delete lags by minutes. You don't need to filter WHERE expiresAt > now() in every query — the database does it for you.

When to Use Record TTL

TTL is the right tool whenever you're tempted to write a "cleanup script that runs every night." Common cases:

• Session tokens — expire after 24 hours of inactivity, or 30 days from creation.
• Verification codes — one-time codes for email verification, magic links, password reset. Expire in 15 minutes.
• Promo codes and flash deals — auto-disable when the deadline hits (or the flash window closes).
• Draft content — autosave drafts that should evaporate after N days unless promoted to a published post.
• Rate-limit windows — track requests-per-minute by storing a record per request with a 60-second TTL.
• Audit logs with retention rules — "delete after 90 days" without writing the cleanup job yourself.
• Cache-like records — when you need durable storage with cache-like eviction.

The negative test: TTL is the wrong tool when you need soft expiration — i.e., the record should be flagged as expired but kept around for analytics or recovery. For that, use a status field (status: 'archived') and filter explicitly. TTL means gone.

Default TTL vs. Per-Record TTL

Most databases that support record TTL let you set it at two levels:

• Default TTL on the collection (or table) — every new record auto-inherits the duration. Set this for collections that are always time-bounded (sessions, verification codes).
• Per-record TTL — override the default (or set TTL on a record in a non-TTL collection). Set this for one-off cases — flash promos in a long-lived "Promotions" table, for example.

A reasonable mental model: default TTL is for the table's intent; per-record TTL is for the exception.

Database TTL vs. DNS TTL

Same name, different concept. They share the underlying idea — "this thing is valid for N seconds, then forget it" — but they apply to different layers:

If you're in the DNS world, TTL is about cache freshness. In the database world, TTL is about automatic cleanup. The mechanics aren't connected — your A-record TTL has nothing to do with your sessions table TTL.

Implementing Record TTL

Most managed databases now offer some form of record TTL: MongoDB has expireAfterSeconds indexes; DynamoDB has TTL attributes; Redis has EXPIRE. The exact API differs, but the shape is the same: a field on the record (or an index on a field) tells the database when to delete.

In Centrali, record TTL is built into the storage layer. You set ttlSeconds or expiresAt when creating a record, or set a default at the collection level:

import { CentraliSDK } from '@centrali-io/centrali-sdk';

const centrali = new CentraliSDK({
  workspaceId: 'my-workspace',
  clientId: process.env.CENTRALI_CLIENT_ID,
  clientSecret: process.env.CENTRALI_CLIENT_SECRET,
});

// Per-record TTL: this verification code expires in 15 minutes
await centrali.createRecord('VerificationCodes', {
  userId: 'user-123',
  code: '482910',
}, { ttlSeconds: 900 });

For a step-by-step walkthrough — sessions with sliding expiration, promo codes with fixed deadlines, draft content with TTL clearing on publish — see the companion post: How to Auto-Expire Records with Centrali TTL. Full reference lives in the Record TTL docs.

Centrali sits in a broader category — a backend for ingesting third-party webhooks, storing them as data, and sending your own webhooks and workflows. Record TTL is one feature inside the storage layer; if you're working with stored Stripe webhook events or schemaless data, the same TTL rules apply to those records.

Common Questions

Does TTL delete data immediately when it expires?
Records become invisible to queries the instant expiresAt passes. Physical deletion happens on a background sweep, typically within a few minutes. Don't rely on instant disk deletion for security-sensitive data — use a separate purge if you need it gone now.

Can I extend a TTL after the record is created?
Yes — update the record with a new ttlSeconds or expiresAt. This is how "sliding expiration" works for sessions: every authenticated request resets the TTL.

Can I remove a TTL after setting one?
Yes — most TTL implementations support clearing the expiration so the record becomes permanent. In Centrali, pass { clearTtl: true } on the update.

Is TTL the same as data retention policy?
TTL is a mechanism for retention. A retention policy is the rule ("keep audit logs for 90 days"); TTL is one way to enforce it. Other ways: scheduled jobs, archival to cold storage, manual purges.

What's the smallest practical TTL?
Depends on the database, but seconds-level TTL is common. Sub-second TTL usually doesn't make sense — by the time the write replicates, the record may already be expired.

Summary

Record TTL is the database equivalent of "set it and forget it" cleanup: assign an expiration to a record, and the database handles the rest. Use it for any data that's intrinsically time-bounded — sessions, codes, promos, drafts, rate-limit windows. Don't confuse it with DNS TTL; same name, different layer.

If you want to see TTL in action with concrete code, the auto-expire records guide walks through three full use cases.

Originally published on centrali.io/blog/what-is-record-ttl. Centrali is the backend for webhooks in and out — ingest third-party webhooks, store them as data, and send your own workflows from one SDK.