2026.10.19 AWS

NoSQL Workbenchの使い方：DynamoDBの設計・ローカル接続・操作手順

Q: NoSQL WorkbenchからDynamoDB Localに接続できないときは何を確認しますか？

確認の順番は3つです。最初にJREの版を java -version で見て、17以上であることを確かめます。次に、接続画面のポートとDynamoDB Localの起動ポートが一致しているか。既定は8000番ですが、他のプロセスが使っていると起動自体が失敗します。最後に、自分で起動したLocalに -sharedDb を付けたかを確認します。付けていないと、アプリとWorkbenchで別のデータベースファイルを見ることになり、テーブルが見えません。

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とは：機能の全体像からローカル起動・キー設計・容量モード選定までで扱っているので、ここではWorkbench固有の部分に絞ります。

設計・実テーブル操作・ローカル検証を担う3機能の役割分担と使う順番

公式Developer GuideのNoSQL Workbenchの項は、このツールを「クロスプラットフォームのクライアント側GUIアプリケーション」と定義しています。役割は次の3つに分かれます。

機能	扱う対象	主な用途
Data Modeler	手元のモデル定義	テーブル・GSI設計とアクセスパターン検証
Operation builder	接続先の実テーブル	参照・更新・PartiQL・コード生成
DynamoDB Local	手元のJavaプロセス	クラウドに出す前の動作確認

使う順番はこの表の上から下です。Data Modelerで設計を固め、DynamoDB Localへコミットして動かし、最後にOperation builderで実環境のデータを確認する。Operation builderから先に触ると、設計の検証を飛ばして実テーブルをいじる流れになりがちです。

3.20.0で入ったアクセスパターン定義と検証できる6種類の操作

公式のリリース履歴によると、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の準備

ダウンロードページには、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の接続画面でLocalタブを選ぶと、入力するのは接続名とポートだけです。DynamoDB Localは画面左下のトグルで起動するか、ターミナルから自分で起動します。どちらでも、接続のポートとLocal側のポートを一致させる必要があります。

自分で起動するなら-sharedDbを付けます。DynamoDB Localの利用上の注意にあるとおり、このオプションを省いた場合のデータベースファイル名は、アクセスキー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です。

AWSアカウントへの接続で長期アクセスキーを使わない一時認証情報の渡し方

AWSアカウントへの接続では、接続名・リージョン・アクセスキーID・シークレットアクセスキーが必須で、セッショントークンとIAMロールARNを任意で指定できます。IAM Identity Centerでログインしているなら、AWS CLIのconfigure export-credentialsで一時認証情報を取り出し、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のインストールと運用にまとめています。

Data Modelerでアクセスパターンを検証してからテーブルを作る手順

DynamoDBの設計はRDBと逆で、テーブルより先に「どの画面がどのキーで何を取るか」を決めます。3.20系のData Modelerは、この順番をそのまま画面の流れにしています。

アクセスパターン先行でテーブル・GSI・サンプルデータを定義する流れ

新規モデルはゼロから作るか、用途の近いサンプルモデルから始めます。アクセスパターンの追加手順に沿うと、作業は次の順になります。

モデルを開き、左側のAccess patternsタブで「+」を押す
名前・説明・操作の種類（Queryなど）・対象のテーブルかGSIを指定する
テーブルにサンプルデータを自動生成するか、CSVから取り込む
Validateタブでパラメータを入れて実行し、返る項目を確かめる
期待と違えばキーやGSIを直し、同じパターンを再実行する

実務では、画面一覧から読み取り系パターンを先に全部登録してから検証に入ると、GSIを足すべき箇所がまとめて見えます。1パターンずつ設計と検証を往復すると、後から来たパターンのためにキーを組み替える手戻りが起きやすくなります。

Validateタブが8001番に立てる一時データベースの仕組みと注意点

検証用には、Workbenchが既定で8001番ポートに別のDynamoDB Localを立て、テーブルとインデックスをメモリ上に作ります。モデルのサンプルデータは自動で投入され、モデルやデータの編集内容も一時テーブルへ自動で反映される仕組みです。アプリを閉じるとこの一時データベースは消えます。

落とし穴は2つあります。8001番を他のプロセスが使っていると検証が始まりません。また、ここでの検証結果は保存されないため、レビュー記録として残したいならモデルをエクスポートしてリポジトリに置く必要があります。8000番で動かしている開発用のLocalとは別物なので、検証用のデータが開発用テーブルに混ざる心配はありません。

CloudFormation JSONでエクスポートしIaCに渡すデプロイの手順

エクスポートの形式は、Workbench同士で共有するためのNoSQL Workbenchモデル形式と、CloudFormation JSONテンプレートの2つです。チーム共有には前者、本番デプロイには後者を使います。受け取る側のAWS::DynamoDB::Tableの最小構成は次の形で、書き出したテンプレートをレビューするときの基準になります。

{
  "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機能でもアカウントへ直接テーブルを作れますが、本番ではCloudFormation経由に寄せます。Commitで作ったテーブルはスタック管理の外に置かれ、後からIaCに取り込む作業が別に発生するからです。テンプレートの書き方とスタック更新の注意点はAWS CloudFormationとはを参照してください。

Operation builderで実テーブルを操作するときの手順と上限値

Operation builderは、接続先の実データを画面から読み書きする機能です。設計検証のData Modelerと違い、ここでの操作は接続先に即座に反映されます。

PartiQLとAPI操作の組み立て・コード生成・保存できる50件の使い分け

API操作の組み立て画面では、Put Item・Update Item・Query・Scanに加え、TransactGetItemsとTransactWriteItemsも組めます。各操作には実行・保存・コード生成のボタンがあり、保存は最大50件です。生成コードは接続情報の扱いを自分の実装に合わせて書き換えてから使います。

SQLに慣れたメンバーはPartiQLから入りがちですが、PartiQLのSELECTはパーティションキーの等価条件か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容量が親に揃う注意点

テーブルのクローンを使うと、DynamoDB LocalとAWSアカウントの間、あるいはリージョンの異なるアカウント間で、キースキーマ・GSIスキーマ・項目をコピーできます。項目数は0件（スキーマだけ）から最大5000件までで、容量モードは既定でオンデマンドです。

GSIの容量設定は、元テーブルの設定がそのまま写ります。プロビジョンドで作るなら、クローン後にUpdateTableでGSIの容量を見直してください。本番データを開発環境へクローンする使い方は、個人情報が含まれるテーブルでは採用しません。5000件の上限があっても、マスキング無しで手元に複製される事実は変わらないからです。

DynamoDB Localで通っても本番で落ちる差分と検証の切り分け

DynamoDB Localは開発とテスト専用で、本番のマネージドサービスと同じではありません。Workbenchで設計を検証した後に残るリスクは、この差分に集中します。

トランザクション競合やベクトルインデックスなどLocalが再現しない挙動

公式の差分一覧から、Workbenchでの検証結果を読み違えやすいものを抜き出すと次のとおりです。

項目	DynamoDB Localの挙動	検証の置き場所
トランザクション競合	TransactionConflict例外なし	モックで例外を注入
ベクトルインデックス	作成を受け付けて無視する	AWSアカウント上
プロビジョンド容量	指定値は無視される	AWSアカウント上
並列スキャン	Segment指定は無視され逐次実行	AWSアカウント上
読み込み整合性	速度のため強い整合性に見える	結果整合性前提で設計

実務でまず押さえるべきは上の2行です。在庫引当のようにトランザクション競合時の再試行が仕様の中心にある処理は、Localで全件成功しても何も証明していません。ベクトル検索の挙動はDynamoDBのベクトル検索とはで扱っている通り、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ポリシー例にある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とはにまとめた内容のとおりです。開発・検証・本番でアカウントを分け、接続ロールと権限を最初から設計したい場合は、一創の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の料金を東京リージョンの実額で試算するで試算しています。