AWS EmulatorでDynamoDBのTTLを試す方法
AWS Emulator を手元で動かすと、AWS のアカウントがなくても、DynamoDB の TTL(Time to Live)を有効にして、期限を過ぎた項目が消えるところを確かめられます。ログインのセッションやワンタイムパスワード、一時的なトークンのように「期限が来たら要らなくなるデータ」を TTL で消す設計を、ローカル環境や CI で試したいときの手順です。検証環境で試したところ、エミュレーターは期限から数秒で項目を消しました。本物の DynamoDB は「期限から数日以内」なので、この差を知ったうえでテストを組む必要があります。
検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.487(2026年11月17日リリース)、AWS CLI 2.40.4 です。AWS のアカウントと認証情報は使っていません。本物の DynamoDB での動き(期限切れの項目が実際に消えるまでの時間、TTL の削除の料金、グローバルテーブルへの複製、Streams の記録の中身)は確かめていません。本物の AWS について書いているところは、公式ドキュメントを出どころにしています。出力の中の12桁のアカウントIDは置き換えています。
エミュレーターを起動して、テーブルを作る
AWS Emulator は、AWS の API を手元で受け付けるエミュレーターです。入れ方と接続の設定は、別の記事「AWS EmulatorをUbuntuに入れて使い始める方法」で詳しく扱っています。ここでは Linux 向けの手順どおりに Debian パッケージを入れ、aws-emulator -t off で起動しました。-t off は、利用状況のデータ(テレメトリー)を AWS に送らない指定です。
AWS CLI は、エミュレーターとは別の端末で、公式ドキュメントにある環境変数を設定してから使います。
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
公式ドキュメントでは、AWS_ENDPOINT_URL が設定されていないシェルでコマンドを実行すると、見つかった認証情報で本物の AWS に送られると注意しています。本物の認証情報があるマシンでは、上の環境変数をすべて設定したシェルで実行してください。
ARN の最後が user/emulator なら、エミュレーターが答えています。
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator
セッションを入れる Sessions テーブルを作ります。あとで削除の記録を見るため、DynamoDB Streams も有効にしました。作った直後に TTL を有効にしようとすると、テーブルがまだ CREATING なので ResourceInUseException になりました。aws dynamodb wait table-exists で ACTIVE になるのを待ってから進めます。
$ aws dynamodb create-table --table-name Sessions --attribute-definitions AttributeName=SessionId,AttributeType=S --key-schema AttributeName=SessionId,KeyType=HASH --billing-mode PAY_PER_REQUEST --stream-specification StreamEnabled=true,StreamViewType=OLD_IMAGE --query TableDescription.TableStatus
"CREATING"
$ aws dynamodb update-time-to-live --table-name Sessions --time-to-live-specification Enabled=true,AttributeName=ExpiresAt
aws: [ERROR]: An error occurred (ResourceInUseException) when calling the UpdateTimeToLive operation: Attempt to change a resource which is still in use: Table is being created: Sessions
$ aws dynamodb wait table-exists --table-name Sessions
$ aws dynamodb describe-table --table-name Sessions --query Table.TableStatus
"ACTIVE"
$ aws dynamodb describe-time-to-live --table-name Sessions
{
"TimeToLiveDescription": {
"TimeToLiveStatus": "DISABLED"
}
}
期限の書き方を変えた項目を入れる
TTL の説明によると、期限は数値(Number)の属性に、1970年1月1日からの秒数(Unix 時間)で入れます。数値でない属性の項目は、TTL の対象になりません。
書き方を間違えたときにどうなるかも見るため、TTL を有効にする前に、期限の入れ方が違う6件を入れました。書き込んだ時刻の Unix 時間は 1794902534(2026-11-17 08:02:14 UTC)です。
| SessionId | ExpiresAt | 中身 |
|---|---|---|
expired |
数値 1794898934 |
1時間前 |
tomorrow |
数値 1794988934 |
1日後 |
string-type |
文字列 "1794898934" |
1時間前を文字列で |
milliseconds |
数値 1794898934000 |
1時間前をミリ秒で |
no-ttl |
なし | 属性を入れない |
six-years-ago |
数値 1605686534 |
6年前 |
書き込みは put-item です。1件目は次のとおりで、ほかの5件も ExpiresAt だけを変えて入れました。
$ aws dynamodb put-item --table-name Sessions --item '{"SessionId":{"S":"expired"},"ExpiresAt":{"N":"1794898934"}}'
$ aws dynamodb scan --table-name Sessions --query "Items[].[SessionId.S, ExpiresAt]" --output json | jq -c ".[]"
["expired",{"N":"1794898934"}]
["milliseconds",{"N":"1794898934000"}]
["no-ttl",null]
["six-years-ago",{"N":"1605686534"}]
["string-type",{"S":"1794898934"}]
["tomorrow",{"N":"1794988934"}]
TTL を有効にすると、期限切れの項目は数秒で消えた
TTL を有効にするのは update-time-to-live です。期限を入れる属性の名前を AttributeName に指定します。直後の状態は ENABLING でした。
$ aws dynamodb update-time-to-live --table-name Sessions --time-to-live-specification Enabled=true,AttributeName=ExpiresAt
{
"TimeToLiveSpecification": {
"Enabled": true,
"AttributeName": "ExpiresAt"
}
}
$ aws dynamodb describe-time-to-live --table-name Sessions
{
"TimeToLiveDescription": {
"TimeToLiveStatus": "ENABLING",
"AttributeName": "ExpiresAt"
}
}
1秒ごとに状態と残っている項目を調べると、5秒後には ENABLED になり、expired と six-years-ago が消えていました。左の数字は update-time-to-live を実行してからの秒数で、状態か項目が変わったときだけ表示しています。
3s ENABLING | expired milliseconds no-ttl six-years-ago string-type tomorrow
5s ENABLED | milliseconds no-ttl string-type tomorrow
残った4件を見ると、期限の書き方を間違えた項目は消えずに残っていました。
$ aws dynamodb scan --table-name Sessions --query "Items[].[SessionId.S, ExpiresAt]" --output json | jq -c ".[]"
["milliseconds",{"N":"1794898934000"}]
["no-ttl",null]
["string-type",{"S":"1794898934"}]
["tomorrow",{"N":"1794988934"}]
文字列で入れた string-type は、公式ドキュメントのとおり TTL の対象になりませんでした。ミリ秒で入れた milliseconds は、秒として読むと何万年も先の時刻になるので、1時間前のつもりでも消えません。JavaScript の Date.now() はミリ秒を返すため、1000で割ってから入れます。
six-years-ago は、本物の DynamoDB と違う結果でした。TTL の期限の計算方法の説明には、5年より前の期限は削除の対象にならないと書かれています。エミュレーターでは、6年前の期限の項目も消えました。5年より前の期限を入れたテストは、エミュレーターで通っても、本物の DynamoDB では消えません。
期限が来てから消えるまでの秒数
TTL を有効にしたあとで、期限を5秒後から25秒後にした5件(in-5s〜in-25s)を入れ、get-item で見つからなくなる時刻を調べました。5件を順に確かめ、1秒待つことを繰り返しました。
in-5s: 期限 P+5s / 見つからなくなった P+8.8s(直前に見つかったのは P+4.6s)
in-10s: 期限 P+10s / 見つからなくなった P+12.9s(直前に見つかったのは P+9.4s)
in-15s: 期限 P+15s / 見つからなくなった P+16.4s(直前に見つかったのは P+13.5s)
in-20s: 期限 P+20s / 見つからなくなった P+21.7s(直前に見つかったのは P+19.4s)
in-25s: 期限 P+25s / 見つからなくなった P+27.1s(直前に見つかったのは P+25.5s)
P は5件を書き込んだ時刻です。どれも期限から4秒以内に見つからなくなりました。直前に読めた時刻と、見つからなくなった時刻の差は1.6〜4.2秒です。in-25s は、期限を0.5秒過ぎても読めました。

本物の DynamoDB では、こうはなりません。UpdateTimeToLive の API リファレンスによると、期限切れの項目はふつう期限から2日以内に消え、TTL の説明では「数日以内」とされています。消えるまでのあいだは、読み取りやクエリ、スキャンの結果にそのまま出てきます。
期限切れのデータを使ってはいけない処理(ログインのセッションの確認など)は、エミュレーターで期限どおりに消えても、TTL の削除に頼らず、読むときに期限を比べます。
期限切れの項目を読まないフィルター式
期限切れの項目を扱う方法の説明では、スキャンやクエリにフィルター式を付けて、期限が今より後の項目だけを返す方法が紹介されています。エミュレーターでは期限切れの項目がすぐ消えてしまうので、TTL を有効にする前の6件で試しました。:now には、実行した時刻の Unix 時間を入れています。
$ aws dynamodb scan --table-name Sessions --filter-expression 'ExpiresAt > :now' --expression-attribute-values '{":now":{"N":"1794902538"}}' --query 'Items[].SessionId.S' --output text
milliseconds tomorrow
ExpiresAt > :now だけだと、ExpiresAt のない no-ttl も返りません。期限のない項目も読みたいなら、attribute_not_exists を足します。
$ aws dynamodb scan --table-name Sessions --filter-expression 'attribute_not_exists(ExpiresAt) OR ExpiresAt > :now' --expression-attribute-values '{":now":{"N":"1794902539"}}' --query 'Items[].SessionId.S' --output text
milliseconds no-ttl tomorrow
ミリ秒で入れた milliseconds は、フィルター式でも「まだ期限が来ていない」として残りました。期限の単位の間違いは、TTL でもフィルター式でも見つからないので、書き込む側のテストで確かめます。
TTL の設定は、続けて変えられない
TTL を有効にした直後に、設定をもう一度変えようとすると、どれも ValidationException になりました。属性の名前を変える操作も、無効にする操作も通りませんでした。
$ aws dynamodb update-time-to-live --table-name Sessions --time-to-live-specification Enabled=true,AttributeName=ExpiresAt
aws: [ERROR]: An error occurred (ValidationException) when calling the UpdateTimeToLive operation: TimeToLive is already enabled
$ aws dynamodb update-time-to-live --table-name Sessions --time-to-live-specification Enabled=true,AttributeName=Other
aws: [ERROR]: An error occurred (ValidationException) when calling the UpdateTimeToLive operation: TimeToLive is active on a different AttributeName: current AttributeName is ExpiresAt
$ aws dynamodb update-time-to-live --table-name Sessions --time-to-live-specification Enabled=false,AttributeName=ExpiresAt
aws: [ERROR]: An error occurred (ValidationException) when calling the UpdateTimeToLive operation: Time to live has been modified multiple times within a fixed interval
UpdateTimeToLive の API リファレンスによると、本物の DynamoDB では変更が終わるまで最大1時間かかり、そのあいだの同じテーブルへの UpdateTimeToLive は ValidationException になります。エミュレーターで新しく作ったテーブルには、作ってすぐ(ACTIVE になったあと)TTL を有効にできました。テストで TTL の設定を変えたいときは、テーブルを作り直します。
DynamoDB Streams に残った削除の記録
TTL で消えた項目は、DynamoDB Streams に REMOVE として記録されていました。ただし、5件(in-5s〜in-25s)の REMOVE は、最後の削除から10秒待って読んでも出てこず、別の項目を1件書き込んだあとに読むと出てきました。
$ aws dynamodb put-item --table-name Sessions --item '{"SessionId":{"S":"another-write"}}'
$ jq -r '.Records[] | [.eventName, .dynamodb.Keys.SessionId.S, (.userIdentity // "なし" | tostring)] | @tsv' records.json
(INSERT の行は省略)
REMOVE expired なし
REMOVE six-years-ago なし
REMOVE in-5s なし
REMOVE in-10s なし
REMOVE in-15s なし
REMOVE in-20s なし
REMOVE in-25s なし
上の一覧の3列目は記録の userIdentity で、どれも入っていませんでした。records.json は、Streams の記録を最初から読んで保存したファイルです。次のように、シャードの先頭(TRIM_HORIZON)から get-records を読み、返ってきた NextShardIterator で続きを読んで、Records をつなげました。
ARN=$(aws dynamodb describe-table --table-name Sessions --query Table.LatestStreamArn --output text)
SH=$(aws dynamodbstreams describe-stream --stream-arn $ARN --query 'StreamDescription.Shards[0].ShardId' --output text)
IT=$(aws dynamodbstreams get-shard-iterator --stream-arn $ARN --shard-id $SH --shard-iterator-type TRIM_HORIZON --query ShardIterator --output text)
aws dynamodbstreams get-records --shard-iterator $IT > page.json
Streams で TTL の削除を見分ける方法の説明では、TTL で消えた項目の記録には userIdentity が入り、type が "Service"、principalId が "dynamodb.amazonaws.com" になると説明しています。アプリが自分で消した項目と TTL で消えた項目を userIdentity で見分ける処理(Lambda で TTL の削除だけを拾う、など)は、このエミュレーターでは確かめられません。
$ jq '[.Records[] | select(.eventName=="REMOVE")][0] | {eventName, eventSource, userIdentity, Keys: .dynamodb.Keys}' records.json
{
"eventName": "REMOVE",
"eventSource": "aws:dynamodb",
"userIdentity": null,
"Keys": {
"SessionId": {
"S": "expired"
}
}
}
エミュレーターで確かめられるのは、TTL を有効にする手順、期限の書き方を間違えた項目が消えないこと、フィルター式の書き方まででした。消えるまでの時間と、Streams の記録の userIdentity は公式ドキュメントの説明と違ったので、そこに頼る処理は、エミュレーターの結果だけで判断しないようにします。




