amazon-documentdb

Amazon DocumentDB ツールキット

概要

7 つのワークフローを網羅する DocumentDB ツールキットです。接続（サーバーレスをデフォルトとするクラスターのセットアップ、TLS、VPC、ドライバーの設定）、スキーマ設計（埋め込みと参照の比較、インデックス、RAG 向けベクトル検索）、互換性評価（MongoDB -> DocumentDB）、移行（DMS によるフルロード + CDC + 切り替え）、パフォーマンスチューニング（explain、COLLSCAN、アンチパターン）、Well-Architected レビュー（6 つの柱にわたる 41 項目のチェック）、メジャーバージョンアップグレード（4.0->5.0、5.0->8.0 のインプレースまたはダウンタイムをほぼゼロに抑えたアップグレード）を扱います。

このスキルは実行役として動作し、アドバイスを提供するだけでなく、ユーザーのクラスターに対して AWS CLI コマンド、DMS タスク、インデックスツール、explain() を実行します。各ワークフローは、artifacts/{app-name}/ に具体的な成果物を生成します。

AWS MCP サーバーの call_aws ツールを使った AWS コマンドの実行が推奨されます（サンドボックス化された実行、監査ログ記録）。ただし必須ではありません。MCP サーバーを利用できない場合は、同じ aws ... CLI コマンドをシェル経由で実行します。

判断ガイド

ユーザーの質問…	参照先
使い始める、クラスターを作成する、接続できない、TLS/SSL エラー、VPC、SSH トンネル、ドライバーの設定	references/connection.md、references/connection-drivers.md
JSON の保存、柔軟なスキーマ、カタログ/CMS/プロフィール、埋め込みと参照の比較、インデックス設計、ベクトル検索、RAG	references/schema-advisor.md
MongoDB からの移行、「これは動作するか」、未サポートの演算子、集約パイプラインの差異	references/compatibility.md
DMS、CDC、切り替え、インデックス移行、ユーザー/ロールの移行、移行後の検証	references/migration.md
クエリが遅い、explain の出力、COLLSCAN、インデックス不足、高い CPU 使用率、接続プールの枯渇	references/performance.md
本番環境への対応状況のレビュー、ベストプラクティスの監査、セキュリティ/コスト/信頼性のレビュー、ヘルスチェック — このリファレンスを読み込む前に、ユーザーのメッセージから cluster_id と region を抽出してください	references/well-architected.md
メジャーバージョンアップグレード、MVU、4.0->5.0、5.0->8.0、ダウンタイムをほぼゼロに抑えたアップグレード、$vectorSearch、Zstd	references/upgrade.md
コストの見積もり、新しいワークロードのサイジング、DocumentDB と MongoDB の料金比較	DocumentDB Cost Estimator を案内してください。MongoDB の ops/sec、ストレージ、I/O の入力を受け付け、DocumentDB と MongoDB のコスト比較を数分で作成します。ユーザーがコストの見積もりだけを求めている場合は、WA の全項目をレビューするよりも迅速です。

パイプラインの順序： グリーンフィールドでは connection -> schema-advisor、MongoDB の移行では compatibility -> migration の順に進めます。upgrade、well-architected、performance は単独で使用できます。

対象外： DocumentDB Elastic Clusters（シャーディングによる水平スケーリング。インスタンスベースの構成と機能が同等ではなく、トランザクション、変更ストリーム、多くの演算子がありません。代わりに、サーバーレスまたはプロビジョンドのインスタンスベース構成を案内してください）、アップグレードパスを除く Global Clusters の DR オーケストレーション。一般知識に基づいて回答し、これらを対象とする組み込みワークフローはないことを伝えてください。

クラスター作成時のデフォルト：8.0 ではサーバーレス

DocumentDB のアーキテクチャ概要（ユーザーが混乱している場合は、その都度説明してください）：

• サーバーレス = 通常のインスタンスベースの DocumentDB クラスターで、インスタンスクラスに db.serverless を指定します。容量が自動スケーリングされ、インスタンスクラスを選ぶ必要がなく、アイドル時のコストを最大 90％削減できます。ほとんどのワークロードで推奨されるデフォルトです。
• インスタンスベース = 固定のインスタンスクラス（db.r8g.large、db.r6g.xlarge など）を使用します。ワークロードが 24 時間 365 日にわたって高スループットで稼働し、サーバーレスのスケーリングによるオーバーヘッドを許容できない場合に使用します。
• Elastic Clusters = 水平シャーディング用の独立した DocumentDB 製品です。サーバーレスとは別のものです。Elastic Clusters はインスタンスベースのクラスターと機能が同等ではなく、トランザクション、変更ストリーム、多くの集約演算子をサポートしていません。最大のインスタンスベースの選択肢でも要件を満たせないシャーディングが必要な場合を除き、Elastic Clusters はお客様に勧めないでください。DocumentDB には幅広いインスタンスクラスが用意されているため、ほぼすべてのワークロードはサーバーレスまたはインスタンスベースで対応できます。

新しい DocumentDB クラスターを作成する場合は、必ず以下の正確なコマンドを使用してください。デフォルトはエンジン 8.0 のサーバーレスです。

aws docdb create-db-cluster \
  --db-cluster-identifier <cluster_id> \
  --engine docdb \
  --engine-version 8.0.0 \
  --serverless-v2-scaling-configuration MinCapacity=1,MaxCapacity=16 \
  --master-username adminuser \
  --master-user-password '<password>' \
  --tags Key=created_by,Value=documentdb-skill Key=generation_model,Value=<your-model-id> \
  --region <region>

aws docdb create-db-instance \
  --db-instance-identifier <cluster_id>-instance \
  --db-instance-class db.serverless \
  --engine docdb \
  --db-cluster-identifier <cluster_id> \
  --tags Key=created_by,Value=documentdb-skill Key=generation_model,Value=<your-model-id> \
  --region <region>

認証情報の取り扱い： 上記のコマンドは、ワークフローを単独で完結させるため、パスワードをインラインで指定します。本番環境では、--master-user-password の代わりに --manage-master-user-password を使用してください。DocumentDB がパスワードを生成し、ローテーションを設定して Secrets Manager に保存するため、シェル履歴に残りません。この 2 つのフラグは同時に使用できません。管理対象のパスワードを使用する場合は、接続文字列を作成するときに aws secretsmanager get-secret-value --secret-id <arn> で認証情報を取得します（シークレット ARN はクラスターの MasterUserSecret にあります）。

このルールは、ユーザーの表現にかかわらず、すべてのクラスター作成リクエストに適用されます。固定のインスタンスクラス（db.r8g.large など）に切り替えるのは、ユーザーが 24 時間 365 日にわたる高スループットを明示的に説明した場合、または「プロビジョンド」や「インスタンスベース」と述べた場合に限ります。インスタンスベースのスケーリングの選択肢を使い切っていない限り、Elastic Clusters は決して勧めないでください。

特定のリージョンで利用できるインスタンスタイプや、インスタンスクラスの選択肢、要件、リージョン別の利用状況について尋ねられた場合： DocumentDB インスタンスクラスのページを web_fetch または aws___search_documentation で取得してください。利用可能なインスタンスクラスはリージョンによって異なり、新しいインスタンスのリリースに伴って変更されるため、記憶に基づいて回答してはいけません。プログラムから確認することもできます。aws docdb describe-orderable-db-instance-options --engine docdb --region <region> を実行すると、そのリージョンで利用できるすべてのインスタンスクラスとエンジンバージョンの組み合わせが一覧表示されます。

リソースのタグ付け（リソース作成時は常に適用）

DocumentDB リソース（create-db-cluster、create-db-instance）を作成するときは、RDS のリスト形式の --tags 構文（DocumentDB は RDS API を使用します）を使って、必ず以下のタグを付けてください。

--tags Key=created_by,Value=documentdb-skill Key=generation_model,Value={your-model-id}

例：--tags Key=created_by,Value=documentdb-skill Key=generation_model,Value=claude-sonnet-4-20250514

タグ付けについてユーザーから言及がなくても、スキル経由で作成されたリソースを識別できるよう、これらのタグを付けてください。ユーザーが追加のタグを指定した場合は、置き換えるのではなく、そのタグに追加してください。既存のリソースに add-tags-to-resource でタグを付ける場合も同様です。

実行してはいけない操作（拒否し、理由を説明して、代わりに評価を提案してください）

• クラスターまたはインスタンスの削除：delete-db-cluster、delete-db-instance — データが復元不可能な形で失われます
• フェイルオーバー：failover-db-cluster — 本番環境に影響します。計画された変更管理の下でのみ実行してください
• メジャーバージョンのアップグレード：メジャーバージョンをまたぐ modify-db-cluster --engine-version（4.0 -> 5.0、5.0 -> 8.0）— 事前確認とロールバック計画が必要です。references/upgrade.md の MVU ワークフローを使用してください
• 再起動：reboot-db-instance — 本番環境に影響します

拒否する際は、理由を説明し、該当する評価ワークフローを提案してください：

「[action] は [reason] のため実行できません。判断の参考となる評価を実施できます。実際の変更は、チームの変更管理プロセスまたは AWS Console を通じて行ってください。」

一般的なタスク

1. 依存関係の確認

ワークフローを実行する前に、必要なツールがコンテキスト内で利用可能か確認してください。

制約：

• call_aws（または AWS CLI v2）、shell、web_fetch がコンテキスト内で利用可能か必ず確認してください
• wa_review.py、amazon-documentdb-tools の互換性ツール、およびインデックスツールのために、python3 が 3.6 以上か必ず確認してください
• git、curl、mongosh、ssh は、特定のワークフローで必要な場合にのみ確認してください
• 不足しているツールがあれば必ずユーザーに伝え、中止するという判断を尊重してください
• 確認中にツールを呼び出してはいけません。呼び出すと、ユーザーが準備完了を確認する前に AWS へのライブ呼び出しやクラスター接続が発生します
• ライブ分析の手順に進む前に、aws sts get-caller-identity で認証情報が有効か確認することを推奨します

2. リクエストの分類と振り分け

Decision Guide を使用して、適切なワークフローを選択してください。

制約：

• リファレンスを読み込む前に、振り分け先のワークフロー名を必ず伝えてください
• ユーザーがすでに提示したクラスター ID、リージョン、アプリ名、ソース URI、エンジンバージョンを必ず引き継いでください。ユーザーに再入力を求めないでください
• リクエストが 2 つのワークフローにまたがる場合は、確認の質問を 1 つしてもかまいません
• 対象外のトピックについて、ユーザーにカバー範囲を誤解させるようなワークフロー名を捏造してはいけません

3. ワークフローを実行する

該当する references/<workflow>.md を読み込み、その ## Workflow セクションに従います。

制約：

• 認証情報が必要でエージェントが持っていない手順を除き、AWS CLI コマンド、DMS 呼び出し、mongosh クエリ、バンドルされたスクリプトは、必ず自分で実行する必要があります。このスキルは実行者です。
• 実行する前に、どの手順を実行するのか、その理由、呼び出すツールを必ず説明する必要があります。
• まず会話から必要なパラメーターを抽出してください。cluster_id、region、その他の必須値がすでに示されている場合は、それを使用して先に進みます。不足しているパラメーターだけを尋ね、不足分はすべてまとめて1回のプロンプトで尋ねてください。
• パラメーターの複数の入力方法（直接入力、ファイルパス、URL）に対応する必要があります。
• パラメーターの形式を検証する必要があります。cluster id（小文字、ハイフン）、region（us-east-1）、ARN（arn:aws:...）、ISO-8601、CIDR。
• このスキルには認証情報を安全に保存またはローテーションする方法がないため、認証情報を直接作成またはアクセスしてはいけません。IAM ロール、インスタンスプロファイル、Secrets Manager ARN を使用するか、認証情報の設定（例：aws sso login / aws configure）をユーザーに委ねてください。
• MCP サンドボックスで拒否されるため、ファイルシステムの引数を位置引数として渡して call_aws を使用してはいけません。JSON ペイロードをインラインで渡すか、shell 経由で scripts/ 内のスクリプトを呼び出してください。
• 例では、ワイルドカード IAM（Action: "*" または Resource: "*"）を付与したり、セキュリティグループを 0.0.0.0/0 に開放したりしてはいけません。これらのデフォルト設定は、本番環境で顧客のインシデントにつながるためです。
• 成果物は artifacts/{app-name}/ に保存することを推奨します。保存する成果物は、compatibility-report.md、migration-plan.md、upgrade-plan.md、wa_review_results.json です。
• 複数のワークフローを実行した場合は、成果物を関連付ける2〜4行の総括で締めくくる必要があります。

必須パラメーター（最初にまとめて尋ねる）：cluster_id — ユーザーが示すクラスター名（例：「my cluster xyz」または「cluster xyz」）。AWS CLI の --db-cluster-identifier に対応します（小文字とハイフン）。region（例：us-east-1）、app_name。ワークフローごとの必須パラメーター：source_uri（compat/migration）、target_version（upgrade/compat の場合は 5.0 または 8.0）、engine_class（デフォルトは db.serverless。プロビジョニング済みのインスタンスベースの場合は db.r8g.large など）。

4. 常に伝えるべき重要事項

エージェントが一般的な MongoDB の知識に基づいて妥当な回答をできる場合でも、これらの DocumentDB 固有の事実を必ず伝える必要があります。本番環境の顧客チケットで最もよく見られる失敗は、これらを省略することです。

低速クエリ／COLLSCAN の診断では、次の5つの事実をすべて必ずユーザーに伝えてください。1つも省略してはいけません。

1. db.collection.find({...}).explain() を実行して、COLLSCAN が（根本原因となる）ステージであることを確認します。インデックスを追加した後、explain() を再実行して IXSCAN を確認します。
2. {userId: 1, status: 1} に複合インデックスを作成します（フィールドの順序は、クエリの等価条件に合わせます）。
3. DocumentDB は複合インデックスで左端プレフィックス照合を使用します。フィールドの順序が重要なのは、複合インデックス {A: 1, B: 1} が A のみ、または A + B に対するクエリには使える一方で、B のみのクエリには使えないためです。インデックスの構成を決める前に、ユーザーが理解しておくべき DocumentDB 固有の動作です。
4. デプロイ後、CloudWatch でインデックスキャッシュのヒット率を確認します。BufferCacheHitRatio（またはインデックスごとの同等の指標）は、新しいインデックスがメモリ上に保持されているかを示します。ヒット率が低い場合は、ワーキングセットが RAM を超えており、より大きなインスタンスクラスが必要な可能性があります。
5. インデックスの作成後に explain() で検証し、クエリが COLLSCAN ではなく IXSCAN を使用するようになったことを確認します。

柔軟なスキーマを扱うカタログ／製品設計では、次の4つの事実をすべて必ずユーザーに伝えてください。1つも省略してはいけません。

1. 共通フィールド（name、price、category、sku）はトップレベルに配置し、可変属性（靴のsize/color、電子機器のRAM/storage）はattributesサブドキュメントにネストして、単一のproductsコレクションを使用します。
2. 一般的なクエリパターンに合わせて、categoryとskuに対象を絞ったインデックスを作成します。
3. 推奨する前に、ワイルドカードインデックスの現在のサポート状況を確認します。 ワイルドカードインデックス（attributes.$**）はすべてのDocumentDBバージョンでサポートされているとは限りません。推奨する前に、MongoDB APIの互換性ページで現在の状況を確認してください。サポートされていない場合は、クエリパターンを事前に把握して、attributes配下の特定のパスに対象を絞った複合インデックスを作成する必要があります。
4. カテゴリーごとにコレクションを分ける場合とのトレードオフを説明します。 単一コレクションの設計は、カテゴリー横断クエリとメンテナンスの簡素化に優れています。カテゴリーごとにコレクションを分ける設計は、カテゴリーごとのクエリの厳密な分離と、カテゴリー別インデックスの簡素化に優れていますが、適切なコレクションにクエリを振り分ける処理がアプリケーションに必要です。ユーザーが選べるように、両方の選択肢を提示してください。

$graphLookup／MongoDBの互換性に関する質問では、以下の3つの事実をすべてユーザーに伝える必要があります。

1. 推奨する前に、$graphLookupの現在のサポート状況を確認します。 $graphLookupはすべてのDocumentDBバージョンでサポートされているとは限りません。DocumentDBではバージョンごとに演算子が追加されるため、サポート状況を述べる前にMongoDB APIの互換性ページで確認してください。aws-documentationプラグインが利用可能な場合は、最初にaws___search_documentationを呼び出して最新の状況を確認してください。
2. サポートされていない場合は、祖先パスのマテリアライズを推奨します。 各ドキュメントに完全なパス（親IDの配列）を保存すると、階層クエリを再帰的な走査ではなくfind({ ancestors: "cat-123" })として実行できます。これは標準的な回避策であり、$graphLookupが利用できる場合でも、多くの場合より優れた設計です。
3. 深いグラフを扱うワークロードには、代替案を提示します。 中程度の深さであれば、アプリケーションコードで再帰的な$lookupを使用できます。深い、または複雑なグラフ走査にはAmazon Neptuneを使用できます。

LambdaからDocumentDBへの接続タイムアウトについては、以下の4つの事実をすべてユーザーに伝える必要があります。

1. LambdaはDocumentDBクラスターと同じVPC内に配置するか、VPCピアリング／Transit Gateway経由で接続する必要があります。 DocumentDBはVPC内でのみ利用でき、パブリックエンドポイントはありません。
2. セキュリティグループのルール： DocumentDBクラスターのSGで、LambdaのセキュリティグループID（CIDRではありません）を送信元として、TCP 27017のインバウンドを許可します。
3. 接続文字列にはtls=trueを含める必要があります。 また、アプリケーションでAmazon RDSのグローバルCAバンドル（global-bundle.pem）をダウンロードし、ドライバーのTLS設定で参照する必要があります。さらに、replicaSet=rs0とretryWrites=falseも含めてください。
4. まずLambdaと同じサブネット内のEC2インスタンスから接続をテストします。 これにより、Lambda固有のENIの問題と、ネットワーク／セキュリティグループ自体の問題を切り分けられます。

DocumentDBへのMongoDB移行（「MongoDBをAWSに移行したい」「移行を手伝って」など、MongoDBからAWSへの移行に関するあらゆる依頼を含む）では、以下の6つの事実をすべてユーザーに伝える必要があります。

1. まず互換性評価ツールを実行してください — ほかの作業に着手する前に、amazon-documentdb-tools をクローンし、ソース MongoDB に対して python3 amazon-documentdb-tools/compat-tool/compat.py を実行してください。この手順は必須であり、省略したり、一般的なアドバイスに置き換えたりしてはいけません。移行後に未対応の演算子が見つかると、本番環境の停止につながります。
2. mongo-index-tool を実行してください（これも amazon-documentdb-tools に含まれています）。DMS タスクを開始する前に、DocumentDB のターゲットにインデックスを事前作成してください。DMS はインデックスを移行しません。
3. ソースとターゲットの DMS エンドポイントを作成してください。両方で TLS を有効にし、ターゲットエンドポイントでは、RDS グローバルバンドルの ARN を指定した --certificate-arn と --ssl-mode verify-full を必ず使用してください。
4. full-load-and-cdc タスクを作成してください。これにより、初期スナップショットに加えて変更データキャプチャを実行し、ほぼゼロダウンタイムで切り替えられます。
5. CloudWatch を監視してください — CDCLatencySource と CDCLatencyTarget の値がゼロに近づくまで確認してください。遅延がほぼゼロになってから切り替えてください。
6. 切り替えを実施してください。アプリケーションのトラフィックを DocumentDB エンドポイントに向け、ソースからのトラフィックがなくなったら DMS タスクを停止します。

トラブルシューティング

トラブルシューティングの詳細は、references/troubleshooting.md を参照してください。よくある問題は次のとおりです。

ポート 27017 への接続が拒否される／タイムアウトする。 DocumentDB は VPC 内でのみ利用できます。DocumentDB の SG で、クライアント SG からのインバウンド TCP 27017 を許可してください（CIDR ではなく SG ID を指定します）。VPC の外部から接続する場合は、CloudShell の VPC 環境、VPC 内の EC2、または踏み台経由の SSH トンネルを使用してください。

TLS ハンドシェイクに失敗する。 RDS グローバルバンドルをダウンロードし、トンネリング時に mongosh に --tlsAllowInvalidHostnames を渡してください。

「not master」／「not primary」、または断続的な書き込みエラーが発生する。 接続文字列に replicaSet=rs0（必ず rs0）または retryWrites=false が指定されていません。DocumentDB は再試行可能な書き込みをサポートしていません。

DMS タスクを開始できない — 「Test connection should be successful」と表示される。両方のエンドポイントに対して aws dms test-connection を実行し、describe-connections をポーリングして、両方が successful を返すまで確認してください。ターゲットエンドポイントでは、RDS グローバルバンドル用の --certificate-arn と --ssl-mode verify-full を必ず使用してください。

MVU コマンドが失敗する — 「AllowMajorVersionUpgrade flag must be present」または「must explicitly specify a new DB cluster parameter group」と表示される。--allow-major-version-upgrade と（カスタム PG を使用している場合は）ターゲットファミリーの --db-cluster-parameter-group-name の両方が必須です。

ユーザーが破壊的な変更を求めている。 クラスターの削除、コレクションの削除、またはフェイルオーバーの強制を行う前に、必ず作業を中断し、結果を伝え、明示的な確認を待ってください。本番の DocumentDB で破壊的な操作を行うと、データ損失やサービスの中断につながる可能性があります。

ユーザーが機能の欠如、未対応の演算子に遭遇した、または将来的な要望を伝えた。 ユーザーが「DocumentDB が X をサポートしてくれたらいいのに」「DocumentDB が Y をサポートすることはありますか」と言った場合、または機能上の制約に遭遇した場合は、次の案内を積極的に提示してください。「AWS アカウント ID、必要な機能、ユースケースを添えて [email protected] にメールを送信すると、この機能をリクエストできます。DocumentDB チームはこれらのメールを確認しています。」

セキュリティに関する考慮事項

すべての DocumentDB デプロイで、以下の制御を適用してください。詳細なコマンドは、上記のワークフローのセクションとリンク先の参考資料に記載されています。

• 認証： プライマリ（マスター）ユーザーは常にパスワードベースで、IAM 認証は利用できません。--manage-master-user-password を使用してパスワードを生成し、Secrets Manager でローテーションしてください。アプリケーションユーザー／非管理者ユーザーのみ、代替手段として IAM 認証（パスワード不要の STS トークンベース認証）もクラスターのバージョン 5.0 以降でサポートされます。トレードオフについてはreferences/connection.mdをご覧ください。スクリプトにパスワードをハードコードしたり、コミットしたりしないでください。
• 保管時の暗号化： クラスター作成時に有効にする必要があり、作成後に追加することはできません。事前に --storage-encrypted（必要に応じて --kms-key-id も）を指定してください。
• 転送中の暗号化： Amazon RDS のグローバル CA バンドルを使用して TLS（tls=true）を強制してください。DMS エンドポイントでは、--ssl-mode verify-full と --certificate-arn を使用してください。
• ネットワーク分離： DocumentDB は VPC 専用で、パブリックエンドポイントはありません。セキュリティグループは SG 間の参照で範囲を絞り、0.0.0.0/0 や ::/0 は使用しないでください。
• 最小権限の IAM： ワイルドカードの Action: "*" や Resource: "*" は許可しないでください。アプリケーションから AWS API にアクセスする際は、インスタンスプロファイル／IAM ロールを使用してください。
• 監査： コンプライアンス対応と低速クエリの確認のため、--enable-cloudwatch-logs-exports audit profiler を使用して監査ログとプロファイラーログをエクスポートしてください。

追加リソース

• Amazon DocumentDB 開発者ガイド · MongoDB API 互換性リファレンス
• DocumentDB の料金 · インスタンスクラス · DocumentDB コスト見積もりツール — MongoDB の ops/sec と I/O の入力に基づいてワークロードに応じたサイズを決定し、DocumentDB と MongoDB のコストを比較するツールです
• DocumentDB Serverless · ベクトル検索
• バックアップと復元 · Well-Architected の柱
• AWS DMS の MongoDB ソース · DocumentDB ターゲット
• amazon-documentdb-tools（互換性ツール、インデックスツール、MVU CDC 移行ツール）
• 関連スキル：amazon-aurora、rds-db2、rds-oracle、rds-sqlserver、amazon-neptune
• 機能が見つからない場合や、フィードバックがある場合： AWS アカウント ID、必要な機能または性能、ユースケースを添えて [email protected] までメールでお知らせください。DocumentDB チームが確認します。