Amazon Documentdb

Amazon DocumentDB Toolkit

Overview

End-to-end DocumentDB toolkit covering seven workflows: connection (serverless-default cluster setup, TLS, VPC, driver config), schema design (embed-vs-reference, indexes, vector search for RAG), compatibility assessment (MongoDB -> DocumentDB), migration (DMS full-load + CDC + cutover), performance tuning (explain, COLLSCAN, anti-patterns), Well-Architected review (41 checks across 6 pillars), and major version upgrade (4.0->5.0, 5.0->8.0 in-place or near-zero-downtime).

The skill acts as an executor — it runs AWS CLI commands, DMS tasks, index tools, and explain() against the user's cluster rather than just advising. Each workflow produces concrete artifacts under artifacts/{app-name}/.

The AWS MCP server is recommended for executing AWS commands via its call_aws tool (sandboxed execution, audit logging), but it is not required — when the MCP server is not available, the same aws ... CLI commands run via shell.

Decision Guide

Pipeline order: connection -> schema-advisor for green-field; compatibility -> migration for MongoDB migrations; upgrade, well-architected, and performance are standalone.

Out-of-scope: DocumentDB Elastic Clusters (sharded horizontal scaling — not at feature parity with instance-based; lacks transactions, change streams, and many operators — steer customers to instance-based serverless or provisioned instead), Global Clusters DR orchestration beyond the upgrade path. Answer from general knowledge, note no bundled workflow covers them.

Cluster Creation Default: Serverless on 8.0

DocumentDB architecture primer (clarify this whenever the user is confused):

• Serverless = db.serverless as the instance class on a normal instance-based DocumentDB cluster. Auto-scales capacity, no instance-class decisions, costs up to 90% less when idle. This is the recommended default for most workloads.
• Instance-based = fixed instance class (db.r8g.large, db.r6g.xlarge, etc.). Use when the workload is sustained 24/7 high throughput and serverless scaling overhead is unacceptable.
• Elastic Clusters = a separate DocumentDB product for horizontal sharding. NOT the same as serverless. Elastic Clusters are not at feature parity with instance-based clusters — they lack support for transactions, change streams, and many aggregation operators. Steer customers away from Elastic Clusters unless they have a sharding requirement that exhausts even the largest instance-based options. Almost all workloads can be served by serverless or instance-based given DocumentDB's wide range of instance classes.

When creating any new DocumentDB cluster, you MUST use these exact commands — default is serverless on engine 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>

Credential handling: the command above takes the password inline for a self-contained workflow. For production, prefer --manage-master-user-password instead of --master-user-password — DocumentDB then generates the password and stores it in Secrets Manager with rotation, keeping it out of shell history. The two flags are mutually exclusive; when you use managed passwords, retrieve the credential with aws secretsmanager get-secret-value --secret-id <arn> (the secret ARN is on the cluster's MasterUserSecret) when building the connection string.

This applies to every create-cluster request regardless of phrasing. Switch to a fixed instance class (db.r8g.large etc.) only if the user explicitly describes sustained 24/7 high throughput or says "provisioned" or "instance-based". Never recommend Elastic Clusters unless the user has exhausted instance-based scaling options.

When the user asks which instance types are available in a specific region, or asks about instance class options, requirements, or regional availability: fetch the live DocumentDB instance classes page via web_fetch or aws___search_documentation — do NOT answer from memory, as available instance classes vary by region and change with new launches. You can also verify programmatically: aws docdb describe-orderable-db-instance-options --engine docdb --region <region> lists every available instance class and engine version combination for that region.

Resource tagging (always apply on resource creation)

When creating any DocumentDB resource (create-db-cluster, create-db-instance), ALWAYS include these tags using the RDS list-of-records --tags syntax (DocumentDB uses the RDS API):

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

Example: --tags Key=created_by,Value=documentdb-skill Key=generation_model,Value=claude-sonnet-4-20250514

Include these tags even if the user does not mention tagging, so that they can identify the resources created via this skill. If the user provides additional tags, append these to their tags rather than replacing them. The same applies when tagging via add-tags-to-resource on existing resources.

Do NOT execute (refuse, explain why, offer assessment instead)

• Delete cluster or instance: delete-db-cluster, delete-db-instance — irreversible data loss
• Failover: failover-db-cluster — production impact, use only under planned change control
• Major version upgrade: modify-db-cluster --engine-version across major versions (4.0 -> 5.0, 5.0 -> 8.0) — requires prechecks and a rollback plan; use the MVU workflow in references/upgrade.md