初級読了 3 分

Docker で DynamoDB Local を動かす方法

DynamoDB Local は、DynamoDB を単一プロセスで再現した AWS のダウンロード可能なエミュレーションです。同じ API、AWS アカウント不要、ネットワーク不要、リクエストごとの請求もありません。ローカルの開発と統合テストに使い、本番では同じコードをクラウドに向ければ済みます。

プロビジョンドスループットを無視し、決してスロットリングしないので、負荷テストや上限テストは実際のテーブルで行うべきです (そのテスト方法は Local がエミュレートしないもので説明しています)。

Docker で DynamoDB Local はどう動かしますか?

docker run -p 8000:8000 amazon/dynamodb-local を実行して公式イメージを起動すると、 http://localhost:8000 で DynamoDB エンジンが公開されます。AWS SDK か CLI を任意のダミー認証情報でそのエンドポイントに向け、クラウドに対するのとまったく同じようにテーブルを作成しリクエストを実行します。

イメージはデフォルトでインメモリで動きます。再起動をまたいでデータを残すにはマウントしたボリューム上で -dbPath を使い、すべてのクライアントと GUI が同じテーブルを見られるように -sharedDb を使います。

コンテナを起動する

docker run -p 8000:8000 amazon/dynamodb-local

これで http://localhost:8000 にエンジンがインメモリで公開されます。すべてのクライアントで 1 つの共有データベースを使うには、イメージのデフォルトコマンドを置き換えます。

docker run -p 8000:8000 amazon/dynamodb-local -jar DynamoDBLocal.jar -inMemory -sharedDb

docker-compose

ほとんどのプロジェクトは、チーム全員が同じエンドポイントを得られるよう docker-compose.yml に固定します。

services:
  dynamodb:
    image: amazon/dynamodb-local
    user: root
    command: '-jar DynamoDBLocal.jar -sharedDb -dbPath /data'
    ports:
      - '8000:8000'
    volumes:
      - dynamodb-data:/data
volumes:
  dynamodb-data:

イメージは非 root の dynamodblocal ユーザーで動作しますが、このユーザーは root 所有の名前付きボリューム内のデータベースファイルを開けません。user: root を付けないと SQLiteException [14] unable to open database file に当たり、あらゆる呼び出しがハングします。

永続化

イメージのデフォルトコマンドは -jar DynamoDBLocal.jar -inMemory を実行するので、コンテナを停止するとすべてのテーブルが消えます。上の compose ファイルはそのコマンドを置き換えています。

  • -dbPath /data とマウントしたボリュームがデータベースファイルをディスクに書き込むので、データは docker compose down を越えて残ります。-dbPath と -inMemory は併用できません。
  • -sharedDb はすべてのクライアントを 1 つのデータベースファイルに載せます。これがないと、インメモリであっても、アクセスキーとリージョンの組み合わせごとに独立したデータベースを持ちます。詳しくは接続ガイドで扱っています。

SDK をそこに向ける

変わるのはエンドポイントだけで、認証情報は任意の英数字のダミー値で構いません。

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({
  endpoint: 'http://localhost:8000',
  region: 'local',
  credentials: {accessKeyId: 'x', secretAccessKey: 'x'}
});

-sharedDb がない場合は、これらの値がデータベースを選びます。別のツールがこのクライアントのテーブルを見られるのは、そのツールもキー x とリージョン local を使うときだけです。

テーブルを作成する

aws dynamodb create-table \
  --endpoint-url http://localhost:8000 \
  --table-name AppData \
  --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
  --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

こうしたシングルテーブルの PK/SK スキーマは良いデフォルトです。フィクスチャを読み込むときは、DynamoDB-JSON コンバーターでプレーンな JSON をワイヤー形式に変換します。

コンテナが立ち上がっていてテーブルが作られたことを確認します。

aws dynamodb list-tables --endpoint-url http://localhost:8000

GUI で閲覧する

CLI 呼び出しはすぐに面倒になります。よくある選択肢はオープンソースの dynamodb-admin ウェブ UI (比較) か、デスクトップクライアントです。 DynoTable は任意の localhost ポートにオフラインの Profile で接続し、独自の使い捨てキーで署名します。そのため、アプリのテーブルを見るには Local を -sharedDb 付きで起動してください (compose ファイルはそうしています)。

あとは、クラウドのテーブルに使うのと同じ UI で、ローカルテーブルの閲覧、 でのクエリ、編集ができます。設定方法は DynamoDB Local と LocalStack への接続にあります。

Local がエミュレートしないもの

Local は API の互換レイヤーだと考えてください。プロビジョンドスループットを無視し、 ProvisionedThroughputExceededException を決して返さず、オンデマンドのバースト挙動もモデル化しません。Local に対する負荷テストは、AWS におけるパーティション上限やアダプティブキャパシティについて何も教えてくれません。

すぐに応答が返るリクエストについては、同じ呼び出しを DynamoDB Local 3.3.2 と DynamoDB に送り、すべてのレスポンスを比較しました。エラーメッセージの大半は異なるため、アサートはエラー名に対して行ってください。AWS 自身が公開している相違点のリストのうち 3 行は、もう当てはまりません。

計画に入れておかないと、統合テストで表に出てくるギャップは他にもあります。

挙動DynamoDB LocalAWS DynamoDB
課金 / RCU / WCUConsumedCapacity を報告するが、何も課金しないリクエストごとに計測
スロットリング起きないあり。テーブル/インデックスの上限で
TTL の削除タイミング期限切れアイテムは数秒以内に消える (実測)通常は期限切れから数日以内
DynamoDB Streams の配信簡略化されている完全なストリームのセマンティクス + Lambda 連携
テーブルをまたぐトランザクションサポート。トランザクションの競合は決して発生しないTransactionConflict の理由でキャンセルされうる
グローバルテーブル / PITR利用不可本番の機能

ギャップごとの対処法は次のとおりです。

  • スロットリングと再試行。 再試行の経路を動かすには、ユニットテストでクライアントをスタブし、呼び出しが ProvisionedThroughputExceededException か ThrottlingException を投げるようにします(これで試せるのは自分のコードの処理です。SDK に組み込まれた再試行まで動かすには、そのエラーコード付きの 400 を返すカスタムのリクエストハンドラーをクライアントに渡します)。あるいは LocalStack を DYNAMODB_ERROR_PROBABILITY=0.2 付きで起動すると、その割合の DynamoDB レスポンスに ProvisionedThroughputExceededException が注入されます (LocalStack の設定)。 LocalStack の起動には LocalStack のアカウントと認証トークンが必要です。無料の Hobby プランは非商用利用向けです。
  • 本物のスロットリング。 低い最大スループットを設定した使い捨てのオンデマンドのクラウドテーブルを使います: aws dynamodb update-table --table-name T --on-demand-throughput MaxReadRequestUnits=1,MaxWriteRequestUnits=1。 AWS はこれをベストエフォートで適用するので、短いスパイクはバーストキャパシティが吸収することがあります。エラーが見えるまで十分長く負荷をかけましょう。最大値を超えたリクエストは ThrottlingException で失敗するので、再試行ハンドラーが ProvisionedThroughputExceededException だけでなくそれも捕捉することを確認してください。
  • TTL。 どの環境でも削除のタイミングをアサートしないでください。 AWS が推奨するとおり、読み取りで期限切れアイテムをフィルタリング (FilterExpression: "#exp > :now") し、各アイテムが正しい TTL 属性を持つことをアサートします。
  • トランザクションの競合。 Local は決して発生させないので、その処理をテストするにはクライアントで TransactionConflict の理由を持つ TransactionCanceledException をモックします。
  • ストリームのファンアウト。 クラウドテーブル、または LocalStack (認証トークンが必要) 上で、ストリームを Lambda につなぎます。

実践的なローカルのワークフロー

よくある構成では、Local を 3 つの層に組み込みます。

  1. CI のセットアップ: CI でコンテナを立ち上げ、beforeAll でテーブルを作成し、 afterAll で片付けます。フィクスチャは小さく保ちましょう。テストが属性マップを手で貼り付けるときは、DynamoDB JSON コンバーターでプレーンな JSON をマーシャルします。
  2. 統合テスト: アプリが使っているのと同じ SDK クライアントのファクトリを、 endpoint と認証情報だけ差し替えて動かします。アサートするのはアイテムの形と条件付き書き込みです。Local はリクエストごとに ConsumedCapacity を返すので、呼び出しごとのユニット数はアサートできますが、そのレートでスロットリングされるかどうかは分かりません。
  3. 手動での探索: オフラインの Profile (Local は -sharedDb 付きで起動) で DynoTable をつなぎ、編集をステージングし、スキーマ変更をデプロイする前に PartiQL やキー条件のクエリを実行します。

単一プロセスでは足りなくなったら (複数のサービス、S3 のトリガー、IAM 相当のルーティング)、 LocalStackか開発用アカウントに進みましょう。 Local は「自分のアクセスパターンは通るか?」を確かめる最速のループであり続けます。

手でマーシャルせずにデータを流し込む

JSON ファイルから 10 件のフィクスチャを読み込む作業は、すべての値に自分で型を付けなくて済むなら速くなります。配列を DynamoDB JSON コンバーターに貼り付け、マーシャルされた出力をコピーし、--endpoint-url http://localhost:8000 に対して BatchWriteItem で一括書き込みします。更新の多いフィクスチャでは、 DynamoDB 式ビルダーで UpdateExpression を組み立て、生成された属性マップをテストハーネスに貼り付けましょう。

DynoTable のアイテムエディターはコミット時に同じマーシャリングを行います。テストの失敗で CLI の生の {"S":...} を眺めるはめになったときに役立ちます。

Local を離れるとき

次のうちどれかを AWS 上で実測する必要があるなら、実際のテーブルに出しましょう。

  • キャパシティ計画: 1 KB のアイテムを秒間 1,000 回読み取ると、オンデマンドでは秒あたり 500 読み取りリクエストユニットかかります (結果整合性で 1 回 0.5)。Local もリクエストごとに同じユニット数を報告しますが、何も課金せず、決してスロットリングしません。アイテムサイズ計算機で得たサイズを使って料金計算ツールで請求額をモデル化してください。
  • インデックス伝播の遅延: 本番では GSI の読み取りは結果整合性ですが、Local はインデックスの行を十分速く返すので、古い読み取りのバグがデプロイまで隠れます。クラウドテーブルに対してアイテムを書き込み、すぐに GSI を Query して、コードがその取りこぼしを許容できるかを確認しましょう。書き込み直後の読み取りが重要な箇所では、代わりにベーステーブルを ConsistentRead: true で読みます。
  • クロスアカウントの IAM: リソース単位のロールや条件キーはクラウドにしかありません。

Local はスキーマと式の構文に対する速いフィードバックのために取っておき、コストと整合性の前提は本番トラフィックの前にステージングのテーブルで検証しましょう。

スクリプトで回避する価値のある落とし穴

  • -sharedDb の付け忘れ: アクセスキーとリージョンの組み合わせごとに独立したデータベースになるので、CI、自分のノート PC、GUI がそれぞれ別のテーブルを見ることになります。
  • user: root なしの root 所有ボリューム: Local はデータベースファイルを開けず、あらゆるリクエストがハングします。SQLiteException は docker logs に出ています。上のセクションの compose の上書きを追加しましょう。
  • Streams が同等だと思い込む: ストリーム連動の Lambda にはクラウドか LocalStack のターゲットが必要です。Local だけではファンアウトを動かせません。
  • 空文字列のキー: 2020 年以降、非キー属性では許可されていますが、キーでは依然として拒否されます。AWS と同じようにフィクスチャを検証しましょう。

DynoTable をダウンロードして、Local を -sharedDb 付きで起動し (上の compose ファイルはそうしています)、ポート 8000 にオフラインの Profile を追加して、本番で使うのと同じグリッド、フィルタービルダー、SQL Workbench でローカルテーブルを閲覧してみてください。ループ中の AWS 支出はゼロです。

著者: Dmitriy · 更新日