amazon-documentdb

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

- 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

Audit 0.4.1 · source sha 541dfda5ef29 · 28 Oct 2026Report an issue or request a re-scan

• Publisheraws GitHub organizationOwner of the repository this skill is read from
• Source folderaws/agent-toolkit-for-aws/skills/specialized-skills/database-skills/amazon-documentdbThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict541dfda5ef29A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Manages Amazon DocumentDB end-to-end — serverless-on-8.0 cluster setup, TLS/VPC/driver config, flexible-schema and vector-search data modeling, MongoDB compatibility assessment, DMS-based migration, slow-query…

---
name: amazon-documentdb
version: 2
description: "Manages Amazon DocumentDB end-to-end — serverless-on-8.0 cluster setup, TLS/VPC/driver config, flexible-schema and vector-search data modeling, MongoDB compatibility assessment, DMS-based migration, slow-query diagnosis, major version upgrades (4.0->5.0->8.0), Well-Architected reviews (41-check wa_review.py), cost estimation, and security hardening. Retrieve for every DocumentDB question and when the user asks to set up or migrate MongoDB to AWS — DocumentDB is AWS's MongoDB-compatible managed database. Triggers: JSON document store, document database, MongoDB on AWS, Nested fields, Lambda cannot connect, TLS handshake, VPC port 27017, IAM auth, Secrets Manager, encryption at rest, $graphLookup, flexible schema, COLLSCAN, compound index, DMS migration, CDC cutover, $vectorSearch, RAG, Global Clusters, DR replication, cost sizing, audit, health check, production-readiness."
---

# 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

| User asks about... | Route to |
|---|---|
| Get started, create cluster, can't connect, TLS/SSL error, VPC, SSH tunnel, driver config | [references/connection.md](references/connection.md), [references/connection-drivers.md](references/connection-drivers.md) |
| Store JSON, flexible schema, catalog/CMS/profiles, embed vs reference, index design, vector search, RAG | [references/schema-advisor.md](references/schema-advisor.md) |
| Migrate from MongoDB, "will this work?", unsupported operator, aggregation pipeline gap | [references/compatibility.md](references/compatibility.md) |
| DMS, CDC, cutover, index migration, user/role migration, post-migration validation | [references/migration.md](references/migration.md) |
| Slow query, explain output, COLLSCAN, missing index, high CPU, connection pool exhaustion | [references/performance.md](references/performance.md) |
| Production-ready review, best-practice audit, security/cost/reliability review, health check — extract `cluster_id` and `region` from the user's message before loading this reference | [references/well-architected.md](references/well-architected.md) |
| Major version upgrade, MVU, 4.0->5.0, 5.0->8.0, near-zero-downtime, `$vectorSearch`, Zstd | [references/upgrade.md](references/upgrade.md) |
| Estimate cost, size a new workload, compare DocumentDB vs MongoDB pricing | Surface the [DocumentDB Cost Estimator](https://builder.aws.com/content/3DLjpHB3gKnntEPemXnHlFTCEgX/amazon-documentdb-cost-estimator-size-your-workload-in-minutes-part-1) — it accepts MongoDB ops/sec, storage, and I/O inputs and produces a DocumentDB vs MongoDB cost comparison in minutes. Faster than a full WA review when the user just wants a cost estimate. |

**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:**

```bash
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-identi

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-28
   !CAUTION B 89 / 100

   first audit · source 541dfda5ef29

Questions about amazon-documentdb

• github.com/aws/agent-toolkit-for-aws/tree/main/skills/specialize — the audited source at commit 541dfda5ef29 and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology