• 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.

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.

db.r8g.large

web_fetch

aws___search_documentation

aws docdb describe-orderable-db-instance-options --engine docdb --region <region>

• 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
• Reboot:

  reboot-db-instance

  — production impact

"I can't perform [action] because [reason]. I can run an assessment to help you decide. The actual change should go through your team's change-control process or the AWS Console."

• You MUST verify

  call_aws

  (or AWS CLI v2),

  shell

  , and

  web_fetch

  are available in context
• You MUST check

  python3

  ≥ 3.6 for wa_review.py, the

  amazon-documentdb-tools

  compat tool, and the index tool
• You MUST check

  git

  ,

  curl

  ,

  mongosh

  , and

  ssh

  only when a specific workflow requires them
• You MUST inform the user of any missing tools and respect a decision to abort
• You MUST NOT invoke the tools during verification because that would trigger live AWS calls or cluster connections before the user confirms they are ready
• You SHOULD confirm credentials are valid with

  aws sts get-caller-identity

  before live-analysis steps

• You MUST name the workflow you are routing to before loading the reference
• You MUST pass along cluster id, region, app name, source URI, and engine versions the user already supplied — they SHOULD NOT re-type these
• You MAY ask one clarifying question if a request straddles two workflows
• You MUST NOT fabricate workflow names for out-of-scope topics because doing so misleads the user about coverage

references/<workflow>.md

## Workflow

• You MUST execute AWS CLI commands, DMS calls,

  mongosh

  queries, and bundled scripts yourself — the skill is an executor unless a step requires credentials the agent doesn't have
• You MUST explain what step is running, why, and which tool is being called before running it
• Extract required parameters from the conversation first — if

  cluster_id

  ,

  region

  , or other required values are already present, use them and proceed. Only ask for missing parameters, and ask for all missing ones together in a single prompt.
• You MUST support multiple input methods for parameters: direct input, file path, or URL
• You MUST validate parameter formats: cluster id (lowercase, hyphens), region (

  us-east-1

  ), ARN (

  arn:aws:...

  ), ISO-8601, CIDR
• You MUST NOT create or access credentials directly because the skill has no safe way to store or rotate them — use IAM roles, instance profiles, Secrets Manager ARNs, or delegate credential setup (e.g.

  aws sso login

  /

  aws configure

  ) to the user
• You MUST NOT use

  call_aws

  with positional filesystem arguments because the MCP sandbox rejects them — pass JSON payloads inline or invoke scripts under

  scripts/

  via

  shell

• You MUST NOT grant wildcard IAM (

  Action: "*"

  or

  Resource: "*"

  ) or open security groups to

  0.0.0.0/0

  in examples because those defaults cause customer production incidents
• You SHOULD save artifacts to

  artifacts/{app-name}/

  :

  compatibility-report.md

  ,

  migration-plan.md

  ,

  upgrade-plan.md

  ,

  wa_review_results.json

• If multiple workflows ran, you MUST close with a 2–4 line synthesis linking the artifacts

cluster_id

--db-cluster-identifier

region

us-east-1

app_name

source_uri

target_version

5.0

8.0

engine_class

db.serverless

db.r8g.large

1. Run

   db.collection.find({...}).explain()

   to confirm

   COLLSCAN

   is the stage (the root cause), and after adding an index, re-run

   explain()

   to confirm

   IXSCAN

   .
2. Create a compound index on

   {userId: 1, status: 1}

   (field order matching the query's equality predicates).
3. DocumentDB uses left-prefix matching on compound indexes — field order matters because a compound index

   {A: 1, B: 1}

   serves queries on

   A

   alone OR

   A + B

   , but never

   B

   alone. This is DocumentDB-specific behavior users must understand before picking an index layout.
4. Check the index cache hit rate via CloudWatch after deployment — the

   BufferCacheHitRatio

   (or the per-index equivalent) indicates whether the new index is staying hot in memory. A low ratio means the working set exceeds RAM and the index may need a larger instance class.
5. Verify with

   explain()

   after the index is created to confirm the query now uses

   IXSCAN

   instead of

   COLLSCAN

   .

1. Use a single

   products

   collection with common fields (name, price, category, sku) at the top level and variable attributes (size/color for shoes, RAM/storage for electronics) nested in an

   attributes

   subdocument.
2. Create targeted indexes on

   category

   and

   sku

   for common query patterns.
3. Check current wildcard index support before advising. Wildcard indexes (

   attributes.$**

   ) may not be supported on all DocumentDB versions — verify current status at the MongoDB API compatibility page before advising. If unsupported: query patterns must be known upfront so targeted compound indexes can be created on specific paths under

   attributes

   .
4. Discuss the tradeoff vs. separate collections per category. Single-collection design wins for cross-category queries and simpler maintenance; separate-collection-per-category wins for strict per-category query isolation and simpler per-category indexing — but requires the application to route queries to the right collection. Name both options so the user can choose.

1. Check current

   $graphLookup

   support status before advising.

   $graphLookup

   is not supported on all DocumentDB versions — verify at the MongoDB API compatibility page before stating support status, as DocumentDB adds operators across versions. If the aws-documentation plugin is available, call

   aws___search_documentation

   to check the live status first.
2. If unsupported: recommend materialized ancestor paths — store each document's full path (array of parent IDs) so hierarchy queries become

   find({ ancestors: "cat-123" })

   instead of recursive traversal. This is the canonical workaround and often the better design even when

   $graphLookup

   is available.
3. Offer alternatives for deep graph workloads — recursive

   $lookup

   in application code for moderate depth, or Amazon Neptune for deep or complex graph traversal.

1. Lambda must be in the same VPC as the DocumentDB cluster, or reach it via VPC peering / Transit Gateway. DocumentDB is VPC-only — no public endpoint.
2. Security group rule: inbound TCP

   27017

   on the DocumentDB cluster's SG, sourced from Lambda's security group ID (not a CIDR).
3. Connection string must include

   tls=true

   and the application MUST download the Amazon RDS global CA bundle (

   global-bundle.pem

   ) and reference it via the driver's TLS config. Also include

   replicaSet=rs0

   and

   retryWrites=false

   .
4. Test connectivity from an EC2 instance in the same subnet as Lambda first — that isolates Lambda-specific ENI issues from pure network/SG problems.

1. Run the compatibility assessor FIRST — before anything else, clone amazon-documentdb-tools and run

   python3 amazon-documentdb-tools/compat-tool/compat.py

   against the source MongoDB. This step is mandatory and must not be skipped or replaced with generic advice. Unsupported operators discovered after migration cause production outages.
2. Run the

   mongo-index-tool

   (also from

   amazon-documentdb-tools

   ) to pre-create indexes on the DocumentDB target before starting the DMS task — DMS does not migrate indexes.
3. Create source and target DMS endpoints with TLS enabled on both; target endpoint MUST use

   --ssl-mode verify-full

   with

   --certificate-arn

   pointing at the RDS global bundle ARN.
4. Create a

   full-load-and-cdc

   task so you get an initial snapshot plus change-data-capture for near-zero-downtime cutover.
5. Monitor CloudWatch — watch

   CDCLatencySource

   and

   CDCLatencyTarget

   until they approach zero. Cut over only when lag is near zero.
6. Cut over by pointing application traffic at the DocumentDB endpoint, then stop the DMS task once traffic is drained from the source.

• Authentication: the primary (master) user is always password-based and cannot use IAM authentication — use

  --manage-master-user-password

  so its password is generated and rotated in Secrets Manager. For application/non-admin users only, IAM authentication is also supported (password-less, STS token-based) on cluster version 5.0+ as an alternative — see the trade-offs in references/connection.md. Never hardcode passwords in scripts or commit them.
• Encryption at rest: enabled at cluster creation and cannot be added afterward — confirm

  --storage-encrypted

  (with an optional

  --kms-key-id

  ) up front.
• Encryption in transit: enforce TLS (

  tls=true

  ) using the Amazon RDS global CA bundle; on DMS endpoints use

  --ssl-mode verify-full

  with

  --certificate-arn

  .
• Network isolation: DocumentDB is VPC-only with no public endpoint. Scope security groups by SG-to-SG reference, never

  0.0.0.0/0

  or

  ::/0

  .
• Least-privilege IAM: never grant wildcard

  Action: "*"

  /

  Resource: "*"

  . Use instance profiles / IAM roles for application access to AWS APIs.
• Auditing: export audit and profiler logs via

  --enable-cloudwatch-logs-exports audit profiler

  for compliance and slow-query review.

• Amazon DocumentDB Developer Guide · MongoDB API compatibility reference
• DocumentDB pricing · instance classes · DocumentDB Cost Estimator — workload-aware sizing tool that takes MongoDB ops/sec and I/O inputs and produces a DocumentDB vs MongoDB cost comparison
• DocumentDB Serverless · vector search
• Backup and restore · Well-Architected pillars
• AWS DMS MongoDB source · DocumentDB target
• amazon-documentdb-tools (compat tool, index tool, MVU CDC migrator)
• Related skills:

  amazon-aurora

  ,

  rds-db2

  ,

  rds-oracle

  ,

  rds-sqlserver

  ,

  amazon-neptune

• Missing a feature or have feedback? Email documentdb-pm@amazon.com with your AWS account ID, the feature or capability you need, and your use case — the DocumentDB team reads these.