DynamoDB TTL and Item Expiration

DynamoDB Time to Live (TTL) is a feature that automatically deletes items from a table after a specified expiration timestamp. It is designed to help you manage the lifecycle of your data without requiring custom code or scheduled jobs to delete old items. TTL is particularly useful for:

TTL operates as a background process on each DynamoDB table partition. You enable TTL by specifying an attribute name that will hold the expiration timestamp. The attribute must store a Unix epoch timestamp in seconds (i.e., the number of seconds since January 1, 1970, 00:00:00 UTC).

Once enabled, DynamoDB performs two main actions: 1. Expiration marking: Within approximately 48 hours after the expiration timestamp passes, DynamoDB's background process scans the partition for items with an expired TTL attribute. When it finds one, it marks the item as expired and removes it from the query and scan results. The item is no longer visible to read operations (GetItem, Query, Scan) after this point. However, the item still physically exists on disk for a short period. 2. Permanent deletion: After an item is marked expired, DynamoDB schedules its permanent deletion. This deletion typically completes within 48 hours of the expiration timestamp, but the exact timing is not guaranteed. The deletion consumes no write capacity units (WCU) because it is handled internally by DynamoDB.

You can enable TTL using the AWS Management Console, AWS CLI, or SDK. The attribute name must be specified at enablement time; you cannot change it later without disabling and re-enabling TTL.

AWS CLI example:

aws dynamodb update-time-to-live \
    --table-name MyTable \
    --time-to-live-specification Enabled=true,AttributeName=expiry

To verify TTL status:

aws dynamodb describe-time-to-live --table-name MyTable

Output:

{
    "TimeToLiveDescription": {
        "TimeToLiveStatus": "ENABLED",
        "AttributeName": "expiry"
    }
}

When writing an item, you set the TTL attribute to a Unix epoch timestamp in seconds. For example, in Python using boto3:

import time
ttl = int(time.time()) + 3600  # expire in 1 hour
table.put_item(
    Item={
        'session_id': 'abc123',
        'data': '...',
        'expiry': ttl
    }
)

You can monitor TTL deletions using Amazon CloudWatch metrics. DynamoDB emits the following metrics: - TimeToLiveDeletedItemCount: The number of items deleted by TTL in a given period. - TimeToLiveExpiredItemCount: The number of items marked as expired by TTL (available in some regions).

These metrics are aggregated at the table level, not per partition.

TTL does not affect IAM permissions. Any user with permission to write to the table can set the TTL attribute. However, the deletion itself is performed by DynamoDB service, not by any user. You cannot prevent TTL from deleting an item once its timestamp has passed, except by updating the TTL attribute to a future time before it is marked as expired.

TTL deletions do not consume WCU. However, updating an item's TTL attribute (e.g., to extend its life) does consume write capacity. The background marking and deletion are free.

A large e-commerce platform uses DynamoDB to store user sessions. Each session has a TTL of 24 hours from the last activity. The application updates the TTL attribute on every user action. When a user logs out, the TTL is set to the current time to force immediate expiration. The TTL background process ensures that stale sessions are automatically cleaned up without a custom garbage collector. This saves significant storage costs (millions of sessions per day) and eliminates the need for a scheduled job. The team monitors TimeToLiveDeletedItemCount to ensure the process is working. A common issue is that if the application fails to update the TTL on user activity, sessions expire prematurely, causing users to be logged out. To mitigate, the team uses a Lambda function triggered by DynamoDB Streams to archive sessions before deletion for audit purposes.

A smart agriculture company collects temperature and humidity readings from thousands of sensors every minute. They store the data in DynamoDB with a TTL of 30 days. After 30 days, the data is automatically deleted. This helps comply with data retention policies and reduces storage costs. The TTL attribute is set to current_time + 30 days when writing each record. The company also uses DynamoDB Streams to feed a Lambda function that copies expired data to Amazon S3 for long-term archival before deletion. A misconfiguration occurred when the development team mistakenly used milliseconds instead of seconds for the TTL timestamp, causing items to never expire. The storage costs skyrocketed until the issue was discovered by monitoring TimeToLiveDeletedItemCount being zero.

A financial services firm must retain transaction records for 7 years and then delete them. They use DynamoDB TTL with a TTL attribute set to 7 years from the transaction date. However, because TTL deletion can take up to 48 hours, they cannot rely on it for exact deletion at the 7-year mark. Instead, they use TTL as a safety net and run a quarterly Lambda function to explicitly delete records that are exactly 7 years old. The TTL ensures that even if the Lambda fails, old records are eventually removed. The firm also enables point-in-time recovery (PITR) to recover accidentally deleted data. They learned that TTL deletions are included in backups, so restoring a backup taken after deletion means the data is permanently gone.