DocumentDB and MongoDB on AWS

Behind the choice sits one question: does your application use any MongoDB feature that DocumentDB documents as unsupported? Run the compatibility checks below against your real queries before committing, because migrating afterwards in either direction is a project.

DocumentDB "supports the MongoDB 3.6, 4.0, 5.0 and 8.0 APIs": drivers written for those protocol levels connect and most CRUD, aggregation, index and transaction code works unchanged. It does not run MongoDB source code, so a feature list per engine version is the contract. The facts that most often decide a project:

Practical method: run the open-source DocumentDB Compatibility Tool (linked from the migration guide) or your own test suite against a development cluster, and keep application code to the intersection of the two feature sets if you may later move to Atlas. The MongoDB concepts behind each of these features are on this site: documents and BSON in Documents, BSON & data types, indexes in Indexing & query performance, transactions in Multi-document ACID transactions, change streams in Reacting to data changes, the aggregation pipeline in The aggregation framework and special indexes and search in Text, wildcard, geospatial & Atlas search. DocumentDB replaces replica-set and sharding administration (Replica sets & high availability, Horizontal scaling with sharded clusters) with managed equivalents, so those pages explain the model rather than commands you run.

Derived from Supported MongoDB APIs, operations, and data types in Amazon DocumentDB, Functional differences: Amazon DocumentDB and MongoDB, engine version support dates and Retryable writes in Amazon DocumentDB.

Everything below creates the orders-api database in us-east-1 inside the Bookshelf VPC (see VPC Networking).

Derived from Get started with Amazon DocumentDB.

The IAM policy of the person or pipeline that provisions the cluster, scoped to the Bookshelf names. The docdb actions use the rds resource ARN namespace because DocumentDB shares control-plane infrastructure with RDS:

Elastic clusters use the docdb-elastic:* action namespace and the AWS managed policy AmazonDocDBElasticFullAccess. At run time the application needs no DocumentDB control-plane permissions, only the ability to read its credentials; this policy goes on the orders-api task role (see Secrets Manager, Parameter Store and KMS):

Derived from Identity and Access Management for Amazon DocumentDB and Password management with Amazon DocumentDB and AWS Secrets Manager.

Spring Data MongoDB talks to DocumentDB through the ordinary MongoDB Java driver, so the mapping model on Spring Data MongoDB applies unchanged: @Document, MongoRepository, MongoTemplate and MongoTransactionManager. Only the connection differs. The Bookshelf orders-api document:

Configuration is a connection string. Credentials come from Secrets Manager through the Spring Cloud AWS config import (see Secrets Manager, Parameter Store and KMS and Configuration and Profiles), so nothing sensitive sits in the repository. With the secret holding the keys username and password, application.yml is:

Three DocumentDB-specific details are in that URI. replicaSet=rs0 plus readPreference=secondaryPreferred makes the driver use the cluster endpoint for writes and spread reads over replicas. retryWrites=false is required on engines before 8.0.2. And tlsCAFile is a convenience of some drivers only: the Java driver ignores it, so either import global-bundle.pem into a JKS trust store passed with -Djavax.net.ssl.trustStore, or bake the trust store into the container image and set the system properties there. In Spring Boot 4 the connection properties moved from spring.data.mongodb. to spring.mongodb. with the old names still accepted for a deprecation period; check the Boot version you use. Set auto-index-creation to false in production and create indexes in a deployment step, because index builds on a live DocumentDB cluster are I/O work you want to schedule. With IAM authentication, replace the user and password with authSource=%24external&authMechanism=MONGODB-AWS and give the orders-api task role (or EKS Pod Identity role) as the database user.

Multi-document transactions work on engine 4.0 and later instance-based clusters when you declare a MongoTransactionManager bean and annotate service methods with @Transactional; keep them short, because DocumentDB limits how long a transaction may run. The semantics (snapshot isolation, write conflicts, retry on transient errors) are described on Multi-document ACID transactions.

Derived from the DocumentDB connecting guide and Spring Data MongoDB reference.

Automated backups are continuous and incremental and stored in Amazon S3; they restore the cluster to any second inside the retention period (1 to 35 days) up to the last five minutes, and they never slow the cluster. Manual cluster snapshots persist until deleted and can be copied to other Regions or shared with other accounts (encrypted snapshots require sharing the KMS key).

Failover to a replica is typically well under a minute and the cluster endpoint follows automatically; with no replica, DocumentDB creates a replacement instance, which takes longer. Global clusters add read-only secondary clusters in other Regions (storage-based replication, typically under a second of lag) for disaster recovery and local reads; they exist for instance-based clusters, need supported instance classes (not the burstable ones) and cannot be elastic. Clones, restore-to-new-cluster and global clusters are the DocumentDB equivalents of the replica-set recovery described on Backups, import/export & GridFS, which still explains the logical-backup option (mongodump) for portable copies.

Derived from Backing up and restoring in Amazon DocumentDB and Amazon DocumentDB global clusters.

Engine 5.0 and 8.0 instance-based clusters support vector indexes (HNSW and IVFFlat) and the $vectorSearch stage on 8.0, so a catalogue of book embeddings can live next to the documents. Create the index with createIndex using a vectorOptions document (dimensions, similarity euclidean, cosine or dotProduct), then query with an aggregation pipeline. For vector-database trade-offs against other engines see Comparing Vector Databases; the MongoDB-flavoured features (Atlas Vector Search, $vectorSearch) are covered on Text, wildcard, geospatial & Atlas search and MongoDB Atlas Search, which apply to Atlas rather than DocumentDB unless noted.

See Monitoring and Observability for the alarm and dashboard patterns that apply to any database.

MongoDB Atlas deploys dedicated clusters (tiers M10 and above), shared and Flex tiers for development, and serverless-style autoscaling into AWS Regions you choose. It speaks genuine MongoDB, adds Atlas Search and Atlas Vector Search, and brings its own backup, monitoring and auto-scaling. Four things matter for the AWS side.

Before migrating, run the compatibility tool against your real workload, verify indexes and the aggregation pipelines in the table above, and decide on retryable writes (8.0.2 and later). Reverse migration to MongoDB or Atlas follows the same steps with DocumentDB as the source.

Derived from Migrating to Amazon DocumentDB and Using MongoDB as a source for AWS DMS.

The database for the orders-api can be the DynamoDB Orders table (Amazon DynamoDB) or this DocumentDB cluster. Choose DocumentDB when the order model is a genuinely nested document queried by several fields, you want aggregation pipelines, or the team already knows MongoDB; choose DynamoDB when every access path is known up front and you want zero capacity management. The Bookshelf wiring is:

Steps: (1) create the bookshelf-orders subnet group, parameter group, cluster and two instances as above; (2) connect as ordersadmin from CloudShell and create the orders_api user and a compound index on customerId and createdAt; (3) store the user’s password as the secret bookshelf/orders/docdb; (4) add the ReadOrdersDbSecret policy to the orders-api task role and sg-orders-db ingress from the task security group (see ECS and Fargate for how task roles and secrets injection work); (5) deploy the Spring Data MongoDB configuration above. A CloudFormation fragment for the cluster, usable beside the baseline in Infrastructure as Code:

Derived from AWS::DocDB::DBCluster.

No prices are quoted here; the numbers change by Region and over time, so use the Amazon DocumentDB pricing page and the AWS Pricing Calculator. The cost drivers for instance-based clusters are:

Atlas bills by tier, storage, backup, data transfer and Atlas Search nodes, even when paid through Marketplace; the cost of PrivateLink is the interface endpoint’s hourly and per-GB charge on the AWS side (see VPC Networking). Cost-control checklist: use db.t4g instances for development and stop them when idle (a stopped cluster restarts automatically after a few days), keep non-production on serverless with a low maximum, set the shortest backup retention that meets your recovery objective, and delete manual snapshots you no longer need. Budget guidance is in Cost Management and Support.

Deletion protection, final snapshots and secret recovery windows protect against mistakes; delete in dependency order. The cluster stops billing for instances as soon as they are deleted, but the cluster’s storage and backups remain until the cluster is deleted.

The managed master-user secret (rds!cluster-…​) is deleted with the cluster. If you used the CloudFormation fragment instead, aws cloudformation delete-stack removes the cluster and, because of DeletionPolicy: Snapshot, leaves a final snapshot to delete separately. For Atlas: terminate the cluster in the Atlas console, delete the private endpoint in Atlas, delete the interface VPC endpoint with aws ec2 delete-vpc-endpoints --vpc-endpoint-ids "$VPCE_ID", and cancel the Marketplace subscription under AWS Marketplace, Manage subscriptions so no new Atlas charges arrive.