AWS EmulatorでDynamoDBのTTLを試す方法

​​AWS Emulator​AWS CLI,DynamoDB

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 は、エミュレーターとは別の端末で、公式ドキュメントにある環境変数を設定してから使います。

bash
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 なら、エミュレーターが答えています。

text
$ 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 になるのを待ってから進めます。

text
$ 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 だけを変えて入れました。

text
$ 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 でした。

text
$ 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 を実行してからの秒数で、状態か項目が変わったときだけ表示しています。

text
3s ENABLING | expired milliseconds no-ttl six-years-ago string-type tomorrow
5s ENABLED | milliseconds no-ttl string-type tomorrow

残った4件を見ると、期限の書き方を間違えた項目は消えずに残っていました。

text
$ 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秒待つことを繰り返しました。

text
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秒過ぎても読めました。

5件の項目それぞれについて、期限の時刻の少しあとに見つからなくなったことを示すグラフ。どれも期限から4秒以内に消えている
期限を5〜25秒後にした項目が見つからなくなった時刻

本物の DynamoDB では、こうはなりません。UpdateTimeToLive の API リファレンスによると、期限切れの項目はふつう期限から2日以内に消え、TTL の説明では「数日以内」とされています。消えるまでのあいだは、読み取りやクエリ、スキャンの結果にそのまま出てきます。

ポイント

期限切れのデータを使ってはいけない処理(ログインのセッションの確認など)は、エミュレーターで期限どおりに消えても、TTL の削除に頼らず、読むときに期限を比べます。

期限切れの項目を読まないフィルター式

期限切れの項目を扱う方法の説明では、スキャンやクエリにフィルター式を付けて、期限が今より後の項目だけを返す方法が紹介されています。エミュレーターでは期限切れの項目がすぐ消えてしまうので、TTL を有効にする前の6件で試しました。:now には、実行した時刻の Unix 時間を入れています。

text
$ 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 を足します。

text
$ 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 になりました。属性の名前を変える操作も、無効にする操作も通りませんでした。

text
$ 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件書き込んだあとに読むと出てきました。

text
$ 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 をつなげました。

bash
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 の削除だけを拾う、など)は、このエミュレーターでは確かめられません。

text
$ 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 は公式ドキュメントの説明と違ったので、そこに頼る処理は、エミュレーターの結果だけで判断しないようにします。

​Posted by 86