DynamoDB Local と LocalStack への接続方法
ローカルで DynamoDB が動いていて、コードはそれに問題なく話しかけている — でも
毎回 scan スクリプトを書くのではなく、テーブルを見たい。クライアントを
ローカルエンドポイントに接続するのは2つの変更です。正しい URL を指定し、使い捨ての
認証情報を渡すこと。以下の詳細は、人がつまずくところです — リージョンの名前空間化、
英数字キーのルール、そして 8000 と 4566 のポートの違いです。
DynamoDB Local と LocalStack: 何に接続しているのか
どちらも AWS アカウントなしで localhost に DynamoDB API を提供しますが、別物です。
- DynamoDB Local は単一プロセスのダウンロード可能な DynamoDB エンジンです — AWS は
JAR と Docker イメージ
（
amazon/dynamodb-local）として提供しています。DynamoDB だけで 他には何もありません。デフォルトポートは 8000 （AWS ドキュメント）。 Docker で DynamoDB Local を実行するを参照してください。 - LocalStack は1つのエンドポイントの背後に複数の AWS サービスのスタックをエミュレートします。その DynamoDB 自体が DynamoDB Local で動いていますが、 すべてが LocalStack の単一の エッジポート 4566を通ります。
つまり接続における実用上の唯一の違いはエンドポイント URL です。スタンドアロンの
DynamoDB Local には :8000、LocalStack 経由の DynamoDB には :4566。それ以外 —
API、認証情報のトリック、GUI 設定 — はすべて同一です。
みんながつまずくエンドポイント + ダミー認証情報のセットアップ
AWS SDK と CLI は、ローカルエンドポイントに話しかけるときでもアクセスキーとリージョンを 要求します — が、それらの値は 本物である必要はありません。AWS 自身のドキュメントは、 これらの値は「ローカルで実行するために有効な AWS の値である必要はない」と述べています （AWS ドキュメント）。
明白でない2つの落とし穴です。
- リージョン/アクセスキーがデータを暗黙に名前空間化します。
-sharedDbフラグがないと、DynamoDB Local はアクセスキー ID + リージョンの組み合わせごとに 別々のmyaccesskeyid_region.dbファイルを書き込みます — AWS の正確な命名です。 アプリが使ったのとは異なるキーやリージョンで接続すると、テーブルが 消えたように見えます。実は別のファイルにあるだけです。-sharedDbで実行する（すべての クライアントに対して1つのshared-local-instance.db）か、アプリが使う正確なキー + リージョンに 合わせましょう。 - アクセスキー ID は英数字でなければなりません — DynamoDB Local では記号は不可です。
AWS ドキュメントは、
AWS_ACCESS_KEY_IDに含められるのはA–Z、a–z、0–9だけだと述べています。AWS は これを DynamoDB Local 2.0.0（および 1.23.0+）で導入したので、以前のイメージで動いていた 特殊文字を含むキーが今は失敗します （AWS re:Post）。 下のエラーを参照してください。
LocalStack の安全なデフォルトは test / test です。
シークレットキーを完全に無視し、
シークレット値を検証することはありません。AKIA…/ASIA… のような本物らしいキーは
安全策として拒否され、ダミーアカウント 000000000000 にフォールバックします —
test のような任意のキーが解決されるのと同じアカウントです。test を使い続けましょう。
AWS CLI での接続（動作確認）
GUI を向ける前に、CLI からエンドポイントが生きているか確認しましょう。CLI は
ローカルエンドポイントをデフォルトにできないので、
すべてのコマンドで --endpoint-url を渡します。
DynamoDB Local:
aws dynamodb list-tables --endpoint-url http://localhost:8000LocalStack（同じコマンド、別のポート）:
aws dynamodb list-tables --endpoint-url http://localhost:4566何らかの認証情報が設定されていれば（~/.aws/credentials 内のフェイクのものや
AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY 経由でも）、これはテーブルのリストを返します。
エラーなしの空リストは、エンドポイントは動いているがあなたが別のキー/リージョンの
名前空間を見ていることを意味します — 上記の落とし穴を参照してください。
DynamoDB Local GUI: DynoTable でローカルテーブルを参照・クエリ
CLI が動いたら、GUI には同じ3つの値が必要です。エンドポイント、リージョン、 そして任意の ダミー認証情報。CLI は目で読む DynamoDB-JSON を返しますが、 GUI は同じデータを、ソート・フィルター・編集できるテーブルとしてレンダリングします。
DynoTable では、接続を追加してカスタムエンドポイントを設定します。
- エンドポイント:
http://localhost:8000（DynamoDB Local）またはhttp://localhost:4566（LocalStack） - リージョン: アプリが使うもの — 例
us-east-1。ここではラベルであって、 本物の AWS リージョンではありませんが、同じデータ名前空間に着地するために一致している 必要があります。 - アクセスキー / シークレット: 何でも可（
test/testが慣例）。DynamoDB Local では アクセスキーは英数字のみです。
そこから項目を参照し、Query や Scan を実行し、CLI で JSON を手作業で
マーシャリングする代わりに、行をビジュアルに編集できます。フィクスチャを読み込むときは、
DynamoDB-JSON コンバーターがプレーン JSON をワイヤー
フォーマットに変換し、Query vs Scanがどちらの読み取りを
選ぶべきかを扱っています。
LocalStack DynamoDB ビューアーも同じ手順で — ポートが
4566 に変わるだけです。
DynoTable はローカル専用のデスクトップソフトウェアなので、localhost に向けても
フィクスチャはあなたのマシンに留まります。GUI の全体像については、
DynamoDB GUI 比較を参照してください。
よくあるエラー（リージョンの不一致、ポート、認証情報）
- Connection refused。 間違ったポート —
8000は DynamoDB Local、4566は LocalStack です。コンテナが実際にポートを公開したかも確認してください （docker run -p 8000:8000 amazon/dynamodb-local）。LocalStack では、サービスがhttp://localhost:4566/_localstack/healthで 起動しているか確認してください。 - DynamoDB Local での
The Access Key ID or Security Token is Invalid。 2.0.0（および 1.23.0+）イメージ以降、アクセスキー ID は 英数字のみでなければなりません。 以前のイメージで動いていた記号付きのキーは今は失敗します — 文字/数字 （例test）に置き換え、すべてのツールを一致させて更新してください。 - LocalStack に対する
The security token included in the request is invalid。 これはほぼ常に認証情報ではなく エンドポイント の問題です — SDK クライアントが--endpoint-url/endpoint_urlを取りこぼし、本物の AWS エンドポイントに当たって、ダミーキーが拒否されています。クライアントが実際にhttp://localhost:4566を指しているか確認してください。 - SDK/CLI からの認証情報エラー。 ローカルエンドポイントでも何らかの
認証情報の存在が必要です。SDK の認証情報チェーンが解決するように、
AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY（またはフェイクのプロファイル）を設定してください。 httpとhttps。 ローカルエンドポイントは素のhttpです。https://URL は TLS ハンドシェイクで失敗します。
DynamoDB Local は私の実 AWS テーブルと同じデータですか？
いいえ — ローカルとクラウドは完全に別々のストアです。DynamoDB Local（および LocalStack の DynamoDB）はデータをローカルファイルかメモリに保持します。あなたの AWS アカウントに触れることはなく、 AWS リージョン/アカウントはクライアントレベルでサポートされて いません。それが要点で、 開発とテストのためのものです。 後で同じフィクスチャをクラウドに入れたいなら、 AWS は ローカルで有効らしいキー/リージョン値を使うことを推奨しているので、移行時にエンドポイントを 入れ替えるだけで済みます。出荷前にそのスキーマをモデリングするには、 シングルテーブル設計と GSI vs LSIが、ローカルと本番で変わらない決定事項を扱っています。
FAQ
本物の AWS 認証情報が必要ですか？ いいえ。DynamoDB Local と LocalStack はどちらも ダミー値を受け入れます。それらは存在し、英数字であり（DynamoDB Local では）、 ツール間で一貫している必要があるだけです。
ツールを切り替えるとテーブルが消えるのはなぜ？ -sharedDb がないと、DynamoDB
Local はデータをアクセスキー + リージョンごとに別々の myaccesskeyid_region.db
ファイルに分割します。-sharedDb を使うか、それらの値をどこでも同一に保ってください。
ポート 8000 と 4566 の違いは？ 8000 はスタンドアロン
DynamoDB Local のデフォルト、4566 はエミュレートされたすべてのサービス（DynamoDB を含む）を
前面に置く LocalStack の単一エッジポートです。
1つの GUI で両方に接続できますか？ はい — どちらも同じ DynamoDB API を話します。
エンドポイント URL が変わるだけです（:8000 と :4566）。
DynamoDB Local は無料ですか？ はい。AWS は DynamoDB Local を JAR と Docker イメージとして無償で配布しています — 「プロビジョンドスループット、データストレージ、データ転送のコストはなし」で、 開発とテストのみを意図しており、 本番用ではありません。
ローカルテーブルに対して SQL を実行できますか？ ローカル DynamoDB はクラウドと同じ API を
話すので、同じアクセスパターンのルールが適用されます — そして同じ制限も。DynamoDB の
PartiQL SELECT 文法は
SELECT … FROM … WHERE … ORDER BY だけ — JOIN も GROUP BY も、
COUNT/SUM/AVG のようなグループ化集計関数も
ありません（PartiQL vs SQLを参照）。
DynoTable の SQL Workbench は、ローカルを含むあらゆる接続でそうした分析クエリを実行します。
DynoTable を試して、localhost:8000 や localhost:4566 に直接接続し、
ローカルテーブルを GUI で参照、クエリ、編集してみてください。