--- title: "NoSQL Workbenchの使い方：DynamoDBの設計・ローカル接続・操作手順" url: "https://www.issoh.co.jp/tech/details/18589/" published: 2026-10-19 updated: 2026-10-19 categories: ["AWS"] publisher: "株式会社一創" --- # NoSQL Workbenchの使い方：DynamoDBの設計・ローカル接続・操作手順 NoSQL Workbench for DynamoDBは、AWSが配布しているDynamoDB専用のデスクトップGUIです。テーブル設計を描くData Modeler、実データを読み書きするOperation builder、同梱のDynamoDB Localの3つで構成され、Windows・macOS・Linuxで動きます。2026年2月の3.20.0でData Modelerが作り直され、アクセスパターンを実際のDynamoDB操作として定義・検証できるようになりました。この記事では、インストールとDynamoDB Localへの接続、アクセスパターン先行のデータモデリング、CloudFormationへの書き出し、本番テーブルを安全に覗くための権限設計までを手順で示します。 ## まとめ：NoSQL Workbenchを開発工程に組み込む範囲と避ける使い方 NoSQL Workbenchが一番効くのは、テーブルを作る前の設計レビューです。アクセスパターンを先に登録し、サンプルデータで`Query`が期待どおりの項目を返すかを確かめてから、CloudFormation JSONで書き出してIaCに渡す。この順番なら、キー設計の誤りを本番テーブル作成前に潰せます。 避けるべきは2つ。1つは、本番アカウントへ書き込み可能な長期アクセスキーで接続することです。GUIから`Delete Table`まで実行できるため、参照専用ポリシーと一時認証情報に絞ります。もう1つは、DynamoDB Localで通った結果を本番の挙動とみなすこと。トランザクション競合やベクトルインデックスはLocalでは再現されません。 ## NoSQL Workbenchの3機能と3.20系のData Modeler刷新 まず全体像です。親テーマであるDynamoDBの構成要素やキー設計の考え方は[Amazon DynamoDBとは：機能の全体像からローカル起動・キー設計・容量モード選定まで](https://www.issoh.co.jp/tech/details/17453/)で扱っているので、ここではWorkbench固有の部分に絞ります。 ### 設計・実テーブル操作・ローカル検証を担う3機能の役割分担と使う順番 [公式Developer GuideのNoSQL Workbenchの項](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html)は、このツールを「クロスプラットフォームのクライアント側GUIアプリケーション」と定義しています。役割は次の3つに分かれます。 | 機能 | 扱う対象 | 主な用途 | | ----------------- | ----------- | --------------------- | | Data Modeler | 手元のモデル定義 | テーブル・GSI設計とアクセスパターン検証 | | Operation builder | 接続先の実テーブル | 参照・更新・PartiQL・コード生成 | | DynamoDB Local | 手元のJavaプロセス | クラウドに出す前の動作確認 | 使う順番はこの表の上から下です。Data Modelerで設計を固め、DynamoDB Localへコミットして動かし、最後にOperation builderで実環境のデータを確認する。Operation builderから先に触ると、設計の検証を飛ばして実テーブルをいじる流れになりがちです。 ### 3.20.0で入ったアクセスパターン定義と検証できる6種類の操作 [公式のリリース履歴](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkbenchDocumentHistory.html)によると、3.20.0（2026年2月16日）でData Modelerの画面が刷新され、アクセスパターンに対応しました。2026年10月時点の最新は3.20.2（2026年4月6日）で、DynamoDB Localの起動失敗時のエラー処理とアクセスパターン周りの修正が入っています。 アクセスパターンとして登録できる操作は`Scan`・`Query`・`GetItem`・`PutItem`・`UpdateItem`・`DeleteItem`の6種類です。`BatchGetItem`やトランザクション系はここでは定義できないため、それらはOperation builder側で確かめます。2020年頃の解説記事にある「Visualizerでファセットを眺めて確認する」流れは、旧UIの手順と考えてください。 ## NoSQL Workbenchの導入とDynamoDB Localへの接続手順 インストールから最初の接続までで詰まるのは、Javaの版、ポート、そして接続ごとに別のデータベースファイルを見てしまう問題の3点です。順に潰します。 ### OS別インストーラとLinuxで必要になるlibfuse2・JRE 17の準備 [ダウンロードページ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.settingup.html)には、macOS（IntelとApple silicon）、Windows、Linux（AppImage）の4種類のインストーラが並んでいます。DynamoDB Localはインストール時に同梱され、動かすために必要な環境はJRE 17以上です。Windowsは3.11.0以降、管理者権限なしでも入れられます。 Ubuntu 22.04以降はlibfuse2が既定で入っていないため、AppImageが起動しません。公式の案内どおり、先に次の2つを入れておきます。 ``` sudo add-apt-repository universe && sudo apt install libfuse2 sudo apt update && sudo apt install curl java -version # 17 以上であることを確認 chmod +x NoSQL_Workbench.AppImage && ./NoSQL_Workbench.AppImage ``` JREが16以下のままだと、Workbench本体は起動してもDynamoDB Localのトグルを入れた時点で失敗します。3.20.2でこの失敗時のエラー表示が改善されたので、古い版を使っている場合は先に更新してください。 ### \-sharedDbによるWorkbenchとアプリの同一テーブル参照設定 Workbenchの[接続画面](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.querybuilder.connect.html)でLocalタブを選ぶと、入力するのは接続名とポートだけです。DynamoDB Localは画面左下のトグルで起動するか、ターミナルから自分で起動します。どちらでも、接続のポートとLocal側のポートを一致させる必要があります。 自分で起動するなら`-sharedDb`を付けます。[DynamoDB Localの利用上の注意](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.UsageNotes.html)にあるとおり、このオプションを省いた場合のデータベースファイル名は、アクセスキーIDとリージョンの組み合わせで決まる仕組みです。アプリとWorkbenchで認証情報が違えば別ファイルを見るため、「アプリで作ったテーブルがWorkbenchに出ない」という状態になります。 ``` java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb -port 8000 # PowerShell では -D の引数全体を引用符で囲む java "-Djava.library.path=./DynamoDBLocal_lib" -jar DynamoDBLocal.jar -sharedDb -port 8000 # 別ターミナルで疎通確認（キーは英数字のみ・実在しない値でよい） aws dynamodb list-tables --endpoint-url http://localhost:8000 ``` Local側のアクセスキーIDは英数字しか受け付けません。ハイフンや記号を含むダミー値を入れると接続できないので、`fakeMyKeyId`のような値にします。Dockerでの起動や`docker compose`の設定は親記事で扱っており、イメージは[Docker Hubのamazon/dynamodb-local](https://hub.docker.com/r/amazon/dynamodb-local)です。 ### AWSアカウントへの接続で長期アクセスキーを使わない一時認証情報の渡し方 AWSアカウントへの接続では、接続名・リージョン・アクセスキーID・シークレットアクセスキーが必須で、セッショントークンとIAMロールARNを任意で指定できます。IAM Identity Centerでログインしているなら、AWS CLIの[configure export-credentials](https://docs.aws.amazon.com/cli/latest/reference/configure/export-credentials.html)で一時認証情報を取り出し、3つの値をそのまま貼るのが安全です。 ``` aws sso login --profile dev-readonly aws configure export-credentials --profile dev-readonly --format env # 出力の AWS_ACCESS_KEY_ID ／ AWS_SECRET_ACCESS_KEY ／ AWS_SESSION_TOKEN を # Workbench の接続画面の Access key ID ／ Secret access key ／ Session token に貼る ``` 一時認証情報は期限が切れると接続が落ちます。手間は増えますが、長期キーを端末のGUIに保存しない代わりの対価と割り切るのが妥当です。CLIのプロファイルやSSOの設定は[AWS CLIのインストールと運用](https://www.issoh.co.jp/tech/details/17403/)にまとめています。 ## Data Modelerでアクセスパターンを検証してからテーブルを作る手順 DynamoDBの設計はRDBと逆で、テーブルより先に「どの画面がどのキーで何を取るか」を決めます。3.20系のData Modelerは、この順番をそのまま画面の流れにしています。 ### アクセスパターン先行でテーブル・GSI・サンプルデータを定義する流れ 新規モデルはゼロから作るか、用途の近いサンプルモデルから始めます。[アクセスパターンの追加手順](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.Modeler.AccessPatterns.html)に沿うと、作業は次の順になります。 1. モデルを開き、左側のAccess patternsタブで「+」を押す 2. 名前・説明・操作の種類（`Query`など）・対象のテーブルかGSIを指定する 3. テーブルにサンプルデータを自動生成するか、CSVから取り込む 4. Validateタブでパラメータを入れて実行し、返る項目を確かめる 5. 期待と違えばキーやGSIを直し、同じパターンを再実行する 実務では、画面一覧から読み取り系パターンを先に全部登録してから検証に入ると、GSIを足すべき箇所がまとめて見えます。1パターンずつ設計と検証を往復すると、後から来たパターンのためにキーを組み替える手戻りが起きやすくなります。 ### Validateタブが8001番に立てる一時データベースの仕組みと注意点 検証用には、Workbenchが既定で8001番ポートに別のDynamoDB Localを立て、テーブルとインデックスをメモリ上に作ります。モデルのサンプルデータは自動で投入され、モデルやデータの編集内容も一時テーブルへ自動で反映される仕組みです。アプリを閉じるとこの一時データベースは消えます。 落とし穴は2つあります。8001番を他のプロセスが使っていると検証が始まりません。また、ここでの検証結果は保存されないため、レビュー記録として残したいならモデルをエクスポートしてリポジトリに置く必要があります。8000番で動かしている開発用のLocalとは別物なので、検証用のデータが開発用テーブルに混ざる心配はありません。 ### CloudFormation JSONでエクスポートしIaCに渡すデプロイの手順 [エクスポート](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.Modeler.ExportModel.html)の形式は、Workbench同士で共有するためのNoSQL Workbenchモデル形式と、CloudFormation JSONテンプレートの2つです。チーム共有には前者、本番デプロイには後者を使います。受け取る側の[AWS::DynamoDB::Table](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-dynamodb-table.html)の最小構成は次の形で、書き出したテンプレートをレビューするときの基準になります。 ``` { "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "OrdersTable": { "Type": "AWS::DynamoDB::Table", "DeletionPolicy": "Retain", "UpdateReplacePolicy": "Retain", "Properties": { "TableName": "Orders", "BillingMode": "PAY_PER_REQUEST", "AttributeDefinitions": [ { "AttributeName": "PK", "AttributeType": "S" }, { "AttributeName": "SK", "AttributeType": "S" }, { "AttributeName": "GSI1PK", "AttributeType": "S" } ], "KeySchema": [ { "AttributeName": "PK", "KeyType": "HASH" }, { "AttributeName": "SK", "KeyType": "RANGE" } ], "GlobalSecondaryIndexes": [ { "IndexName": "GSI1", "KeySchema": [ { "AttributeName": "GSI1PK", "KeyType": "HASH" }, { "AttributeName": "SK", "KeyType": "RANGE" } ], "Projection": { "ProjectionType": "ALL" } } ] } } } } ``` ``` aws cloudformation deploy --template-file orders-model.json --stack-name orders-table ``` Workbenchの[Commit機能](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.Modeler.Commit.html)でもアカウントへ直接テーブルを作れますが、本番ではCloudFormation経由に寄せます。Commitで作ったテーブルはスタック管理の外に置かれ、後からIaCに取り込む作業が別に発生するからです。テンプレートの書き方とスタック更新の注意点は[AWS CloudFormationとは](https://www.issoh.co.jp/tech/details/2927/)を参照してください。 ## Operation builderで実テーブルを操作するときの手順と上限値 Operation builderは、接続先の実データを画面から読み書きする機能です。設計検証のData Modelerと違い、ここでの操作は接続先に即座に反映されます。 ### PartiQLとAPI操作の組み立て・コード生成・保存できる50件の使い分け [API操作の組み立て画面](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.querybuilder.operationbuilder.api.html)では、`Put Item`・`Update Item`・`Query`・`Scan`に加え、`TransactGetItems`と`TransactWriteItems`も組めます。各操作には実行・保存・コード生成のボタンがあり、保存は最大50件です。生成コードは接続情報の扱いを自分の実装に合わせて書き換えてから使います。 SQLに慣れたメンバーはPartiQLから入りがちですが、[PartiQLのSELECT](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html)はパーティションキーの等価条件か`IN`が無いと全表スキャンになります。 ``` -- パーティションキーの等価条件あり：Query として動く SELECT * FROM "Orders" WHERE PK = 'CUSTOMER#1001' AND begins_with(SK, 'ORDER#') -- キー以外の条件だけ：全表スキャンになり読み込み容量を一度に消費する SELECT * FROM "Orders" WHERE Total > 500 ``` 見た目はどちらも普通のSQLで、画面上では区別がつきません。大きな本番テーブルに2本目を流すと、1回の実行で読み込み課金がテーブル全体分かかります。 ### テーブルクローンの最大5000件とGSI容量が親に揃う注意点 [テーブルのクローン](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.querybuilder.cloning-tables.html)を使うと、DynamoDB LocalとAWSアカウントの間、あるいはリージョンの異なるアカウント間で、キースキーマ・GSIスキーマ・項目をコピーできます。項目数は0件（スキーマだけ）から最大5000件までで、容量モードは既定でオンデマンドです。 GSIの容量設定は、元テーブルの設定がそのまま写ります。プロビジョンドで作るなら、クローン後に`UpdateTable`でGSIの容量を見直してください。本番データを開発環境へクローンする使い方は、個人情報が含まれるテーブルでは採用しません。5000件の上限があっても、マスキング無しで手元に複製される事実は変わらないからです。 ## DynamoDB Localで通っても本番で落ちる差分と検証の切り分け DynamoDB Localは開発とテスト専用で、本番のマネージドサービスと同じではありません。Workbenchで設計を検証した後に残るリスクは、この差分に集中します。 ### トランザクション競合やベクトルインデックスなどLocalが再現しない挙動 [公式の差分一覧](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.UsageNotes.html)から、Workbenchでの検証結果を読み違えやすいものを抜き出すと次のとおりです。 | 項目 | DynamoDB Localの挙動 | 検証の置き場所 | | ---------- | ----------------------- | ---------- | | トランザクション競合 | TransactionConflict例外なし | モックで例外を注入 | | ベクトルインデックス | 作成を受け付けて無視する | AWSアカウント上 | | プロビジョンド容量 | 指定値は無視される | AWSアカウント上 | | 並列スキャン | Segment指定は無視され逐次実行 | AWSアカウント上 | | 読み込み整合性 | 速度のため強い整合性に見える | 結果整合性前提で設計 | 実務でまず押さえるべきは上の2行です。在庫引当のようにトランザクション競合時の再試行が仕様の中心にある処理は、Localで全件成功しても何も証明していません。ベクトル検索の挙動は[DynamoDBのベクトル検索とは](https://www.issoh.co.jp/tech/details/18270/)で扱っている通り、AWS上でしか確かめられません。 ### 1MB制限の計算差とテーブル名の大文字小文字で起きる取り違え 1回の結果セットが1MBまでという制限はLocalでも働きますが、インデックスを引くときの計算が違います。本番は射影したキーと属性だけを数え、Localは項目全体を数えます。そのため、Localではページングが早く切れ、本番では1ページに多く返る。件数でページ境界を決め打ちしたテストはここで崩れます。 テーブル名も差があります。本番は大文字小文字を区別し、`Authors`と`authors`を別テーブルとして作れます。Localでは区別しないため、2つ目を作成しようとしたときの結果はエラーです。Workbenchのモデルで名前の揺れがあると、Localへのコミットだけが失敗するので、命名規約はモデル作成時点で固めておきます。 ## NoSQL Workbenchを採用する場面とIaCや管理コンソールに任せる場面 ここまでの機能を踏まえ、どの工程でWorkbenchを使い、どこで使わないかを言い切ります。 ### 設計レビューと新規メンバーの立ち上がりでWorkbenchを使う条件 採用するのは、アクセスパターンが5本以上あり、GSIの要否を議論する段階です。パターンとサンプルデータを1つのモデルファイルにまとめてレビューに出せるため、口頭やスプレッドシートで設計を回すより手戻りが減ります。DynamoDBが初めてのメンバーに、キー設計とクエリ結果の関係を体感させる教材としても向いています。 逆に、テーブルが1つでキーも単純なCRUD中心のサービスなら、Workbenchを挟む価値は薄い。CloudFormationかCDKのコードを直接書き、DynamoDB Localに対する自動テストで足ります。Workbenchのモデルファイルとテンプレートの二重管理になると、どちらが正なのかがすぐ曖昧になるため、正本はIaC側に置くと決めておきます。 ### 本番接続を書き込み可能な権限で開かないための参照専用ポリシー Operation builderからは、確認欄にテーブル名を入れるだけでテーブルやGSIの削除まで実行できます。本番アカウントへの接続には、参照系の操作だけを許し、PartiQLの全表スキャンも拒否するポリシーを付けたロールを使います。[PartiQLのIAMポリシー例](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-iam.html)にある`dynamodb:FullTableScan`条件キーを組み合わせると次の形です。 ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["dynamodb:ListTables"], "Resource": "*" }, { "Effect": "Allow", "Action": ["dynamodb:DescribeTable", "dynamodb:GetItem", "dynamodb:Query", "dynamodb:PartiQLSelect"], "Resource": [ "arn:aws:dynamodb:ap-northeast-1:123456789012:table/Orders", "arn:aws:dynamodb:ap-northeast-1:123456789012:table/Orders/index/*" ] }, { "Effect": "Deny", "Action": ["dynamodb:PartiQLSelect"], "Resource": "*", "Condition": { "Bool": { "dynamodb:FullTableScan": ["true"] } } } ] } ``` `Scan`を許可から外しているのは、Operation builderのScanボタンが本番で全件を読みに行くのを防ぐためです。画面の操作で足りない権限が出たら、エラーに出るアクション名を1つずつ足します。ロールとポリシーの設計に関する解説は、[AWS IAMとは](https://www.issoh.co.jp/tech/details/15427/)にまとめた内容のとおりです。開発・検証・本番でアカウントを分け、接続ロールと権限を最初から設計したい場合は、一創の[AWSインフラ構築サービス](https://www.issoh.co.jp/service/system/aws/)で構成設計から支援しています。 ## よくある質問 NoSQL Workbenchの導入時と日々の操作でよく出る質問をまとめます。 ### NoSQL WorkbenchからDynamoDB Localに接続できないときは何を確認しますか？ 確認の順番は3つです。最初にJREの版を`java -version`で見て、17以上であることを確かめます。次に、接続画面のポートとDynamoDB Localの起動ポートが一致しているか。既定は8000番ですが、他のプロセスが使っていると起動自体が失敗します。最後に、自分で起動したLocalに`-sharedDb`を付けたかを確認します。付けていないと、アプリとWorkbenchで別のデータベースファイルを見ることになり、テーブルが見えません。 ### 作ったデータモデルをチームで共有するにはどうしますか？ モデルの三点メニューからExport modelを選び、NoSQL Workbenchモデル形式で書き出したファイルをリポジトリに置きます。受け取る側はメイン画面のImport modelで読み込み、既存プロジェクトか新規プロジェクトへ追加します。プロジェクトを指定しない場合の保存先は、draftsフォルダです。デプロイまで見据えるなら、CloudFormation JSONでも書き出して差分レビューの対象にしてください。 ### 既存のDynamoDBテーブルからデータモデルを作れますか？ Data Modelerが読み込めるのは、NoSQL Workbenchモデル形式とCloudFormation JSONテンプレートの2種類です。既存テーブルがCloudFormationで管理されているなら、そのテンプレートを取り込んでアクセスパターンを足せます。コンソールで手作りしたテーブルは、Operation builderで接続してキーとGSIの構成を読み取り、モデル側に定義し直すのが現実的な手順になります。 ### CSVでデータを取り込んだり書き出したりできますか？ できます。3.2.0以降、Data Modelerへサンプルデータを取り込むときにCSVを使え、Operation builderのクエリ結果はCSVへ書き出せます。3.12.0ではCSV取り込み時にデータが上書きされる不具合が直っているため、古い版で取り込み結果がおかしい場合は更新を先に試してください。大量データの移行用途ではなく、検証用の少量データを扱う機能と考えるのが妥当です。 ### NoSQL Workbenchで作ったテーブルの容量モードは何になりますか？ 既定はオンデマンドです。3.13.5（2025年2月）で、既定設定でのテーブル作成がプロビジョンドからオンデマンドへ変わり、Data ModelerのCommitも既定でオンデマンドのテーブルとインデックスを作ります。Operation builderでプロビジョンドのテーブルを作る場合に必要なのは、既定設定のチェックを外し、読み書きの容量を指定する操作です。容量モードごとの費用の差は[DynamoDBの料金を東京リージョンの実額で試算する](https://www.issoh.co.jp/tech/details/17798/)で試算しています。 ## 関連記事 - [Amazon DynamoDBとは：機能の全体像からローカル起動・キー設計・容量モード選定まで](https://www.issoh.co.jp/tech/details/17453/)：DynamoDB Localのdocker compose起動とキー設計の基礎 - [DynamoDBの料金を東京リージョンの実額で試算する：請求が跳ねる設計と単価の下げ方](https://www.issoh.co.jp/tech/details/17798/)：設計したテーブルの費用見積もり - [AWS CloudFormationとは？テンプレートの書き方・スタック操作と更新で消える設定の防ぎ方](https://www.issoh.co.jp/tech/details/2927/)：書き出したテンプレートの運用 - [AWS IAMとは？仕組み・ユーザー/ロール/ポリシーの違いと権限設計のベストプラクティスを実装者目線で解説](https://www.issoh.co.jp/tech/details/15427/)：本番接続用ロールの設計 - [AWS CLIのインストールと運用｜OS別の導入手順・v2の設定・SSO認証・v1サポート終了への移行](https://www.issoh.co.jp/tech/details/17403/)：一時認証情報を取り出すCLIの設定 --- 出典: [NoSQL Workbenchの使い方：DynamoDBの設計・ローカル接続・操作手順]()（株式会社一創）