DynamoDB TTL

Time to Live (TTL) is a feature that automatically deletes items from a DynamoDB table after a specified expiry time. You do not need to write any code or run any scheduled jobs — DynamoDB handles the deletion on its own.

Why TTL Matters

Many applications store data that is only useful for a limited time. Session tokens expire after a few hours. A password reset link becomes invalid after 10 minutes. Temporary discount codes expire on a specific date. Without TTL, this data accumulates permanently, bloating your table, increasing storage costs, and slowing down queries.

TTL solves this by letting you attach an expiry timestamp to each item. DynamoDB automatically removes it when the time comes.

How TTL Works

You designate one numeric attribute in your table as the TTL attribute. The value must be a Unix epoch timestamp — the number of seconds since January 1, 1970 (UTC). When the current time exceeds an item's TTL value, DynamoDB marks it as expired. DynamoDB then deletes expired items in the background, typically within 48 hours of the expiry time.

Unix Timestamp Examples

Current time:         2024-06-01 10:00:00 UTC → Unix: 1717232400
Expires in 1 hour:    2024-06-01 11:00:00 UTC → Unix: 1717236000
Expires in 24 hours:  2024-06-02 10:00:00 UTC → Unix: 1717318800
Expires in 30 days:   2024-07-01 10:00:00 UTC → Unix: 1719824400

Setting Up TTL

Step 1: Choose a TTL Attribute

Pick a name for the TTL attribute — for example, ExpiresAt. The attribute must be a Number type. You activate TTL in the DynamoDB console or via the AWS CLI by specifying this attribute name.

aws dynamodb update-time-to-live \
  --table-name Sessions \
  --time-to-live-specification "Enabled=true, AttributeName=ExpiresAt"

Step 2: Write Items with the TTL Attribute

PutItem: Session token for user U001 (expires in 2 hours)
{
  "SessionID":  { "S": "sess-abc-123" },
  "UserID":     { "S": "U001" },
  "Token":      { "S": "eyJhbGciOiJIUzI1..." },
  "CreatedAt":  { "N": "1717232400" },
  "ExpiresAt":  { "N": "1717239600" }  ← TTL: now + 2 hours
}

At 1717239600 (after 2 hours), DynamoDB automatically deletes this session item.

TTL Deletion Is Not Instant

DynamoDB deletes expired items in the background. The deletion usually happens within a few minutes to a few hours after expiry, but AWS guarantees it within 48 hours. This means an item may still be readable for a short period after its TTL timestamp passes.

How to Handle This in Your Application

If your application reads items that might be expired but not yet deleted, add a check in your code:

After reading a session item:
  IF current_time > item.ExpiresAt:
    Treat the item as invalid
    Do NOT allow the user to proceed
    (Optional: delete the item immediately with DeleteItem)

Do not rely solely on TTL deletion for security-sensitive expiry enforcement. Always validate the timestamp in your application logic as well.

Diagram: TTL Lifecycle

T=0:00 → Item written with ExpiresAt = T+2hrs
T=1:00 → Item readable (not expired)
T=2:00 → Item EXPIRED (TTL timestamp passed)
T=2:00 → Item still physically in table (deletion pending)
T=2:15 → DynamoDB background process deletes item
T=2:15 → Item no longer readable ✓

TTL and DynamoDB Streams

When TTL deletes an item, it generates a stream record with EventName = "REMOVE" and a userIdentity field indicating the deletion came from TTL (not from an application). This lets you distinguish TTL deletions from explicit application deletes in your stream processing logic.

Stream record from TTL deletion:
{
  "eventName": "REMOVE",
  "userIdentity": {
    "type": "Service",
    "principalId": "dynamodb.amazonaws.com"
  },
  "dynamodb": {
    "OldImage": { ... expired item ... }
  }
}

You can use this stream record to archive expired items to Amazon S3 before they disappear permanently.

TTL Does Not Consume Write Capacity

TTL deletions are free — they do not consume your table's WCUs. This is a significant benefit for tables with high expiry volumes. In provisioned mode, if you deleted expired items manually using DeleteItem calls, each deletion would cost 1 WCU. With TTL, those deletions cost nothing.

Items Without a TTL Attribute

TTL only applies to items that have the designated TTL attribute. Items without the attribute (or with a non-numeric or future value) are never automatically deleted. You can mix TTL-enabled and non-TTL items freely in the same table.

Common TTL Use Cases

Summary

• TTL automatically expires and deletes items using a Unix timestamp attribute.
• Enable TTL by specifying the TTL attribute name at the table level.
• Deletion happens within 48 hours of expiry — usually much sooner.
• TTL deletions are free (no WCU cost) and appear in Streams as REMOVE events.
• Validate TTL in your application for security-critical logic — do not rely solely on background deletion.