DynamoDB LocalとLocalStackへの接続方法
ローカルのDynamoDBが動いていて、コードはそれと問題なく通信できている。でも、毎回scanスクリプトを書くのではなく、テーブルを見たい。クライアントをローカルエンドポイントに接続するのは2つの変更だけです。正しいURLに向けて、使い捨ての認証情報を渡す。
以下の細部こそ、みんながつまずくところです。リージョンの名前空間分け、英数字キーのルール、そして8000と4566のポートの違いです。
DynamoDB Local vs LocalStack:何に接続するのか
どちらもAWSアカウントなしでlocalhost上のDynamoDB APIを提供します(LocalStackにはLocalStackのアカウントが必要です。後述)。ただし、両者は別物です。
- DynamoDB Localは単一プロセスのダウンロード可能なDynamoDBエンジンです。AWSはこれをJARとDockerイメージ(
amazon/dynamodb-local)として配布しています。DynamoDBそのものであり、それ以外はありません。デフォルトポートは 8000(AWSドキュメント)。 DockerでDynamoDB Localを動かすを参照してください。 - LocalStackは一群のAWSサービスを1つのエンドポイントの背後でエミュレートします。そのDynamoDB自体も
DynamoDB Localで動いていますが、すべてのサービスがLocalStackの単一のポート4566を通ります。リリース2026.03.0以降、
localstack/localstackイメージはLocalStackの認証トークン(LOCALSTACK_AUTH_TOKEN)がないと起動しないため、LocalStackのアカウントが必要です。無料のHobbyプランは非商用利用向けで、商用利用には有料プランが必要です(料金)。DynamoDBだけが必要なら、DynamoDB Localは無料でアカウントも不要です。
ですから接続における実用的な違いはエンドポイントURLです。スタンドアロンの
DynamoDB Localには:8000、LocalStack経由のDynamoDBには:4566。APIと認証情報のトリックは同じです。
CLIでDynamoDB-JSONを読む代わりにローカルテーブルをグリッドで参照したいなら、 DynoTableはオフラインのProfileで接続します。ポートとリージョンだけで、入力するキーはありません(設定)。
エンドポイントとダミー認証情報
AWS SDKとCLIは、ローカルエンドポイントと通信するときでもアクセスキーとリージョンを要求します。ただしそれらの値は本物である必要はありません。AWS自身のドキュメントは、これらの値は"don't have to be valid AWS values to run locally"と述べています(AWSドキュメント)。
リージョン/アクセスキーが、データをひそかに名前空間分けする。
-sharedDbフラグがないと、DynamoDB LocalはアクセスキーID+リージョンごとに別々のデータベースを、myaccesskeyid_region.dbという名前のファイルに保持します(AWSの正確な命名)。この分割はメモリ上でも同じです。
-inMemoryで起動したDynamoDB Local 3.3.1では、localでキーxを使って作成したテーブルは、us-east-1のキーdummyからは見えませんでした。アプリが使ったのと違うキーやリージョンで接続すると、テーブルが消えたように見えます。対処:DynamoDB Localを
-sharedDb付きで起動する(すべてのクライアントに対して1つのshared-local-instance.db)か、アプリが使うキー+リージョンを正確に合わせましょう。 LocalStackも認証情報とリージョンごとに別々のデータベースを保持するので、コンテナをDYNAMODB_SHARE_DB=1付きで起動します。アクセスキー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です。LocalStackはシークレットキーを完全に無視し、シークレットの値を一切検証しません。本物らしいAKIA…/ASIA…キーは安全策として拒否され、ダミーアカウント000000000000にフォールバックします。これはtestのような任意のキーが解決されるのと同じアカウントです。testのままにしておきましょう。
AWS CLIで接続する(動作確認)
GUIを向ける前に、エンドポイントが生きていることをCLIから確認しましょう。CLIには組み込みのデフォルトローカルエンドポイントがないので、コマンドごとに--endpoint-urlを渡すか、
AWS_ENDPOINT_URL_DYNAMODB=http://localhost:8000を設定します(CLI v2.13以降)。
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が動いたら、すべてのクライアントが1つのデータベースを共有するようにエンジンを起動します。DynoTableはローカルへのリクエストに独自の固定の使い捨てキーで署名するので、エンジンがキーごとにデータを分割しない場合にだけ、アプリのテーブルが見えます。
# DynamoDB Local: override the image's default command to add -sharedDb
docker run -p 8000:8000 amazon/dynamodb-local -jar DynamoDBLocal.jar -inMemory -sharedDb
# LocalStack: one shared DynamoDB database (needs your LocalStack auth token)
docker run -p 4566:4566 -e LOCALSTACK_AUTH_TOKEN=<token> -e DYNAMODB_SHARE_DB=1 localstack/localstack次に、DynoTableでProfileを追加します。
- Profile の種類: オフライン。
- ポート:
8000(DynamoDB Local)または4566(LocalStack)。このProfileは常にhttp://localhost:<port>に接続します。 - AWS リージョン: アプリが使うリージョンを一覧から選びます(例:
us-east-1)。-sharedDb付きのDynamoDB Localならどれでも構いません。LocalStackではアプリのリージョンに合わせてください。
アクセスキーの入力欄はありません。Profileが独自の英数字の使い捨てキーを提供します。そこから項目を参照し、QueryやScanを実行し、CLIでJSONを手でマーシャリングする代わりに項目を編集できます。
フィクスチャを読み込むときは、DynamoDB-JSONコンバーターがプレーンなJSONをワイヤーフォーマットに変換し、Query vs Scanがどちらの読み込みを使うべきかをカバーします。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でサービスが起動しているか、そしてLOCALSTACK_AUTH_TOKENを渡したかを確認しましょう。これがないとコンテナは起動しません(理由はdocker logsに出ます)。 - 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。 DynamoDB Localは素のhttpを話すので、https://のURLは TLSハンドシェイクに失敗します。LocalStackはhttp://localhost:4566とhttps://localhost.localstack.cloud:4566の両方を受け付け、後者のために証明書を公開しています。
DynamoDB Localは本物のAWSテーブルと同じデータ?
いいえ。ローカルとクラウドは完全に別々のストアです。DynamoDB Local(および LocalStackのDynamoDB)はデータをローカルファイルまたはメモリに保持します。あなたの AWSアカウントには一切触れず、ローカルでは AWSのリージョン/アカウントはクライアントレベルではサポートされません。それこそが狙いです。これは開発とテストのためのものです。
AWSは、移行時にコードはエンドポイントを差し替えるだけで済むよう、ローカルでも有効らしいキー/リージョン値を使うことを提案しています。データは置いていかれます。クラウドのテーブルにシードするには、フィクスチャのローダーを本物のエンドポイントに対して再実行します(BatchWriteItem、1回の呼び出しで25アイテム)。
出荷前にそのスキーマをモデリングするには、シングルテーブル設計と GSI vs LSIが、ローカルと本番で変わらない意思決定をカバーしています。
ローカルが節約するもの(と本番がなお課金するもの)
ローカルはリクエストごとの消費キャパシティを報告しますが、何も課金せず、スロットルもしません。クラウドはすべての読み取りと書き込みに課金します。それが何を隠すかは Local を離れるときで扱っています。そのジャンプは料金計算機でモデルし、代表的なアイテムのサイズはアイテムサイズ計算機で見積もってください。
よくある質問
本物のAWS認証情報は必要? いいえ。DynamoDB LocalもLocalStackもダミー値を受け付けます。ただ存在していて、(DynamoDB Localでは)英数字で、エンジンが 1つの共有データベースで動いていない限りツール間で一貫していればよいだけです。 LocalStackは起動に独自の認証トークンが必要ですが、DynamoDB Localには何も要りません。
ツールを切り替えるとテーブルが消えるのはなぜ? -sharedDbがないと、
DynamoDB Localはアクセスキー+リージョンごとに1つのデータベースを保持します。名前空間の落とし穴を参照してください。
ポート8000と4566の違いは? 8000はスタンドアロンのDynamoDB Localのデフォルト、4566はエミュレートされた全サービス(DynamoDBを含む)の前面に立つ
LocalStackの単一ポートです。
DynamoDB Localは無料? はい。AWSはDynamoDB LocalをJARと Dockerイメージとして無料で配布しており、"no provisioned throughput, data storage, or data transfer costs"です。開発とテストのみを想定しており、本番向けではありません。
ローカルテーブルに対してSQLを実行できる? ローカルのDynamoDBはクラウドと同じAPIを話すので、同じアクセスパターンのルールが適用され、同じ制限もあります。
DynamoDBの
PartiQL SELECT文法は
SELECT … FROM … WHERE … ORDER BYのみで、JOINもGROUP BYも、
COUNT/SUM/AVGのようなグループ化集計関数もありません(PartiQL vs SQLを参照)。DynoTableの
SQL Workbenchは、それらの分析クエリを、ローカルを含む任意の接続に対して実行します。
DynoTableを試す:1つの共有データベースでエンジンを起動し(上記のとおり
-sharedDbまたはDYNAMODB_SHARE_DB=1)、ポート8000または4566でオフラインの
Profileを追加すれば、ローカルテーブルをGUIで参照・クエリ・編集できます。