Amazon DocumentDB
DocumentDB is a managed document database that speaks the MongoDB wire protocol, so MongoDB drivers and most application code connect unchanged. AWS handles patching, backups, replication, and failover. It sits between RDS (relational) and DynamoDB (key-value) for applications wanting a flexible JSON-document model with relational-style indexes.
The surprise everyone hits: DocumentDB is not MongoDB. It is an AWS engine that emulates the MongoDB API — compatibility is good for common features but not 100%. Check AWS's compatibility matrix before migrating an existing MongoDB application.
The Data Model
A database holds collections of documents — BSON objects (JSON plus types like ObjectId and Date), schemaless beyond what the application writes, up to 16 MB each. Indexes are explicit: single-field, compound, multikey on arrays, text, and geospatial. The closest SQL analogy is "tables of JSON documents with indexes you choose."
Cluster Architecture
DocumentDB borrows Aurora's architecture: one writer plus up to fifteen readers on a shared distributed cluster volume spanning three AZs with six copies of every block, and reader-to-writer failover in seconds. This shared-storage design is the main reason to pick it over running MongoDB on EC2 — and it carries Aurora's trade-off that a cluster cannot scale writes beyond a single writer.
Three endpoints mirror Aurora: cluster endpoint (writer), reader endpoint (DNS round-robin across readers), and instance endpoints for diagnostics. Connect with a MongoDB driver with TLS enabled.
Compatibility Differences
Compatibility is good but incomplete: DocumentDB is not sharded (one writer), some aggregation-pipeline stages and operators are unsupported, hashed indexes are not available, and authentication is IAM or SCRAM rather than Kerberos or LDAP. The supported feature set has grown steadily since 2019, so re-check the matrix before each major migration.
DocumentDB — a managed document database with the MongoDB API and Aurora-style durability, when most-but-not-all MongoDB features suffice.
DynamoDB — key-value/document workloads needing horizontal write scaling and serverless single-digit-ms latency.
MongoDB Atlas — full MongoDB feature parity and sharding — a third-party SaaS on AWS, when DocumentDB's compatibility gaps block you.
- Assuming DocumentDB is MongoDB — it emulates the API; verify the compatibility matrix before migrating an existing app.
- Expecting to shard writes across nodes — DocumentDB has a single writer like Aurora; use DynamoDB for horizontal write scale.
- Running a cluster with only a writer and no reader in another AZ, slowing failover (same rule as Aurora).
- Relying on unsupported features (hashed indexes, certain aggregation operators, Kerberos/LDAP) discovered only after migration.
- Letting documents grow without bound toward the 16 MB limit instead of fixing the underlying schema design.
- Putting the master password on the command line — DocumentDB lacks managed-master-password support, so use Secrets Manager directly.
- Check the AWS compatibility matrix before migrating any MongoDB application.
- Run at least one reader in a different AZ from the writer.
- Use connection pooling to handle many short-lived document-store requests.
- Index the fields you query (you can add indexes later, but building them scans the collection).
- Enable encryption at rest at creation — the same one-way decision as Aurora and RDS.
- Design schemas to stay well under the 16 MB document limit.
Knowledge Check
What is the most important thing to verify before migrating a MongoDB app to DocumentDB?
- The AWS compatibility matrix — DocumentDB emulates the MongoDB API and is not 100% compatible
- That the application happens to be written in JavaScript using the official Node.js MongoDB driver
- That every document the app stores stays under the 400 KB size threshold
- That the cluster has cluster mode enabled turned on before the cutover
How does DocumentDB's cluster architecture compare to Aurora's?
- It is the same: one writer plus up to fifteen readers on a shared distributed volume across three AZs
- It shards incoming writes across many fully independent writer nodes, unlike Aurora's single-writer design
- It stores all of the cluster's data on one single instance with no replication or redundancy at all
- It uses DynamoDB's hash-based partitioning model rather than a shared volume
A workload needs to scale write throughput horizontally across many nodes. Is DocumentDB a fit?
- No — DocumentDB has a single writer; DynamoDB is the AWS-native answer for horizontal write scale
- Yes — DocumentDB automatically shards incoming writes evenly across all of the available cluster nodes
- Yes — simply add more reader instances and writes will spread across them
- Yes — enable cluster mode enabled to distribute writes across shards
What is the maximum size of a DocumentDB document?
- 16 MB, including all field names and values
- 400 KB, counting all field names and stored values
- 1 GB, counting all field names and stored values
- There is no fixed limit on a single document's size
You got correct