What Is Amazon DocumentDB? Pricing, Free Trial, Serverless, DocumentDB vs MongoDB and DynamoDB, Connection Guide and Errors

Amazon DocumentDB (with MongoDB compatibility) is AWS's managed JSON document database: it speaks the MongoDB wire protocol, so applications, drivers and tools built for MongoDB 4.0, 5.0 and 8.0 connect to it with little or no change, while AWS runs the servers, storage, replication, backups and patching. You pay for instances by the hour (from $0.0757 an hour, about $54 a month, for a db.t4g.medium, or $0.263 an hour for a db.r6g.large), storage at $0.10 per GB-month and $0.20 per million I/Os on the Standard configuration, or a higher storage price with no I/O charges on I/O-Optimized. DocumentDB Serverless bills $0.0822 per DCU-hour and scales from 0.5 to 256 DCUs, and Elastic Clusters shard to petabytes at $0.132 per vCPU-hour. New customers get a one-month free trial of 750 hours of db.t3.medium. One thing surprises everyone: DocumentDB has no public endpoint, so you connect from inside your VPC (or through a tunnel), always with TLS and retryWrites=false. Below: what DocumentDB is and how it works, DocumentDB vs MongoDB Atlas and DynamoDB, every price with worked examples, Serverless and Elastic Clusters, connecting with mongosh, Compass and Python, migration from MongoDB, limits, versions, and fixes for the connection errors almost everyone hits.

The furniture store's new online shop had been built by a web agency on MongoDB, running on a single virtual machine the agency rented. The catalog suited documents perfectly: a sofa has fabric, seats and recline options; a lamp has bulbs and wattage; a rug has pile height. But the one machine had no replica, backups were a script nobody had tested, and the agency was about to stop hosting it. The owner wanted it inside the store's AWS account. Jake asked whether "MongoDB on AWS" meant renting a bigger virtual machine. Ethan opened the DocumentDB console instead.

New to AWS databases? The cards below cover subnets, Secrets Manager, DynamoDB costs, ElastiCache and billing alerts, the pieces a DocumentDB cluster usually sits next to.

What is Amazon DocumentDB?

A document database stores data as JSON-like documents rather than rows in tables. Each document can have its own shape: one product has seats and fabric, another has wattage, and neither needs empty columns for the other. Nested objects and arrays live inside the document, so a product and its variants, images and reviews can be read in one query. MongoDB is the best-known document database, and its query language, drivers and tools are what most developers learn.

Amazon DocumentDB is AWS's managed document database that is compatible with the MongoDB API. It is not MongoDB's own code: AWS built it on its own distributed storage engine (the same family of technology behind Aurora) and implemented the MongoDB wire protocol on top. In practice, your app connects with the normal MongoDB driver, runs the same find, insertOne and aggregate calls, and most things just work. Some MongoDB features are missing or behave differently, which is the main thing to check before you move.

What AWS manages for you:

• Storage that grows automatically, replicated six ways across three Availability Zones.
• Replicas: up to 15 read replicas per cluster, with automatic failover if the primary fails.
• Backups: continuous backups with point-in-time restore, plus manual snapshots.
• Patching, monitoring and encryption: engine updates in maintenance windows, CloudWatch metrics, encryption at rest with KMS and TLS in transit.
• Scaling options: bigger instances, more replicas, Serverless capacity that follows load, or Elastic Clusters that shard across many nodes.

Jake: "So it's MongoDB, but AWS looks after it."

Ethan: "It's something that talks exactly like MongoDB to our app. Most of the time that's the same thing. The few times it isn't are what we test first."

How DocumentDB works: clusters, instances and storage

1. A cluster is the database: one shared storage volume plus one or more instances that read and write it.
2. The primary instance handles all writes (and reads, if you want); replica instances serve reads from the same storage, typically only milliseconds behind.
3. The storage volume keeps six copies of your data across three Availability Zones and grows automatically as you add data, up to 128 TiB (256 TiB on version 8.0).
4. Endpoints route your app: the cluster endpoint always points at the primary; the reader endpoint spreads reads across replicas; each instance also has its own endpoint.
5. If the primary fails, DocumentDB promotes a replica to primary, usually in well under a minute, and the cluster endpoint follows it, so apps reconnect without configuration changes.
6. Backups run continuously to S3 behind the scenes, so you can restore to any second within your retention window (1 to 35 days).

Because compute and storage are separate, adding a replica does not copy any data, and it is ready in minutes. It also means you can stop a whole cluster (for up to seven days) and pay only for storage while it is stopped, handy for development environments.

Is DocumentDB NoSQL? Yes: it is a non-relational (NoSQL) document database, queried with the MongoDB query language rather than SQL, although JDBC and ODBC drivers let BI tools such as Tableau run SQL-style queries against it. What is it used for? Product catalogs, content management, user profiles and preferences, mobile and web app backends, IoT and event data with flexible shapes, and, with vector search, storing embeddings next to documents for AI search and retrieval.

DocumentDB vs MongoDB Atlas, MongoDB on EC2 and DynamoDB

	Amazon DocumentDB	MongoDB Atlas	Amazon DynamoDB
What it is	AWS-built, MongoDB API compatible	MongoDB Inc.'s managed MongoDB, on AWS, Azure or Google Cloud	AWS serverless key-value and document database
Query language	MongoDB API (most of it)	Full, latest MongoDB	DynamoDB API and PartiQL; queries by key
Rich queries and aggregations	Yes, with secondary indexes	Yes, the most complete	Limited; design tables around access patterns
Pricing model	Instances or DCUs per hour + storage + I/O	Cluster tiers per hour, plus a free tier cluster	Per request (on-demand) or capacity, + storage
Scale	128 to 256 TiB per cluster; Elastic Clusters to petabytes	Sharded clusters, very large	Practically unlimited, single-digit millisecond
Network access	Inside your VPC only	Public endpoint with IP allow-list, or private link	Public AWS API endpoint (or VPC endpoint)
Best for	MongoDB apps that want AWS-native operations, IAM, billing	Apps needing every MongoDB feature, Atlas Search, multi-cloud	High-scale key lookups, serverless apps, spiky traffic

• DocumentDB vs MongoDB (Atlas or self-managed): if your app uses mainstream MongoDB features (CRUD, indexes, common aggregation stages, transactions, change streams), DocumentDB is a straightforward managed home on AWS, with IAM, VPC isolation, CloudWatch, AWS Backup and a single AWS bill. If you rely on newer or niche MongoDB features, Atlas Search, specific aggregation stages or the very latest server versions, run real MongoDB: Atlas, or MongoDB on EC2 (which means you manage replication, backups and upgrades yourself). Check the list of supported APIs before deciding; it is short to scan and saves surprises.
• DocumentDB vs DynamoDB: DynamoDB is serverless, scales almost without limit, bills per request, and is ideal when you know your access patterns (get item by ID, query by partition). DocumentDB is the better fit when you need flexible ad-hoc queries, multi-field filters, aggregations, or existing MongoDB code. On cost, a small DocumentDB cluster has a fixed hourly floor (around $54 a month), while a quiet DynamoDB table can cost cents; at steady high load, a well-sized DocumentDB cluster can be cheaper than heavy DynamoDB read and write traffic.
• DocumentDB vs OpenSearch: OpenSearch is a search and analytics engine (full-text relevance, log analytics, dashboards); DocumentDB is a database of record. Many teams keep the data in DocumentDB and stream it to OpenSearch for search.
• DocumentDB vs S3: S3 stores files and objects cheaply but cannot query inside JSON documents by field with indexes; DocumentDB is for data your app reads and updates constantly.
• DocumentDB vs Aurora PostgreSQL with JSONB: if most of your data is relational with some JSON fields, PostgreSQL's JSONB columns may be enough; if everything is documents and your team thinks in MongoDB, DocumentDB fits better.

Amazon DocumentDB pricing

US East (N. Virginia) prices in October 2026 for instance-based clusters:

Instance	vCPU / memory	Standard, per hour	I/O-Optimized, per hour	Standard, per month (720 h)
db.t4g.medium	2 / 4 GiB	$0.0757	$0.0832	$54.48
db.t3.medium	2 / 4 GiB	$0.078	$0.0858	$56.16
db.r6g.large	2 / 16 GiB	$0.263	$0.289	$189.47
db.r8g.large	2 / 16 GiB	$0.276	$0.304	$198.75
db.r6g.xlarge	4 / 32 GiB	$0.526	$0.579	$378.94
db.r6g.2xlarge	8 / 64 GiB	$1.053	$1.158	$757.87

• Storage: Standard $0.10 per GB-month plus $0.20 per million I/O requests; I/O-Optimized $0.30 per GB-month with no I/O charges and instances about 10 percent dearer. I/O-Optimized usually wins once I/O is more than about a quarter of your DocumentDB bill.
• Backups: free up to 100 percent of your cluster's storage; beyond that, $0.021 per GB-month.
• Serverless: $0.0822 per DCU-hour (Standard) or $0.0905 (I/O-Optimized), billed per second; a DCU is about 2 GiB of memory with matching CPU and network.
• Elastic Clusters: $0.132 per vCPU-hour, $0.30 per GB-month of storage, $0.021 per GB-month of snapshots.
• T-instance CPU credits: sustained high CPU on t3 and t4g instances is billed at $0.09 per vCPU-hour of extra credits.
• Global clusters: replicated write I/Os to each secondary Region at $0.20 per million, plus the secondary Region's instances, storage and cross-Region data transfer.
• Version 3.6: clusters still on DocumentDB 3.6 pay an Extended Support premium from July 1, 2026: 80 percent extra on the instance price in years one and two, 160 percent in year three. Upgrading to 5.0 or 8.0 removes it.
• Savings: DocumentDB is covered by Database Savings Plans, which cut steady database spend by up to 35 percent in exchange for an hourly commitment; see our Savings Plans decision tree.
• Data transfer: free between DocumentDB and EC2 in the same Availability Zone and for replication between AZs; app traffic across AZs is billed at normal regional rates.

Is there a DocumentDB free tier?

There is a one-month free trial for eligible new customers: 750 hours of db.t3.medium instance usage, 30 million I/Os, 5 GB of storage and 5 GB of backup storage, for 30 days. That is enough to run one small instance around the clock for a month and try your application against it. It is not available in AWS GovCloud (US) or China (Ningxia), and after the 30 days the normal rates apply, so delete or stop the trial cluster if you are not keeping it. There is no permanently free DocumentDB, unlike DynamoDB's free tier; accounts created from July 15, 2025 can also use Free Tier credits.

Two details catch trial users. The free hours are for db.t3.medium only, so creating the cluster on db.t4g.medium or an R instance is billed from the first hour. And 750 hours is one instance for a month: a cluster with a primary and a replica uses the allowance twice as fast, so for a trial, create a single-instance cluster. For learning the MongoDB API itself at no cost, a local MongoDB or a free MongoDB Atlas cluster works; switch to DocumentDB when you want to test the AWS-specific parts.

Worked examples: what DocumentDB really costs

Example 1: a development cluster. One db.t4g.medium, 20 GB of data, 10 million I/Os a month: $54.48 + $2.00 + $2.00 = about $58.50 a month. Stopping it outside working hours (it can stay stopped up to seven days at a time) cuts the instance part by more than half.

Example 2: the store's production catalog. Three db.r6g.large instances (a primary and two replicas in different AZs), 200 GB of data, 500 million I/Os a month, on Standard storage: instances 3 x $189.47 = $568.40, storage $20, I/O $100. About $688 a month. The same cluster on I/O-Optimized: instances 3 x $0.289465 x 720 = $625.24, storage 200 x $0.30 = $60, I/O $0. About $685 a month, nearly the same, with a bill that no longer depends on traffic.

Ethan: "Six hundred and eighty-five a month, with three copies of the shop across three data centers and backups every second."

Jake: "The agency's machine cost forty."

Ethan: "And it was one disk failure away from closing the shop. We can start with two instances and a smaller size; that's about $380."

Example 3: a heavy-traffic month. If the store's I/O tripled to 1.5 billion during a sale, Standard storage would add $300 of I/O; I/O-Optimized would add nothing. That predictability is why busy apps choose I/O-Optimized.

Example 4: Serverless for a spiky app. An internal tool busy 8 hours a day at an average of 2 DCUs, idling at the 0.5 DCU minimum the rest of the time: (8 x 2 + 16 x 0.5) x 30 = 720 DCU-hours x $0.0822 = $59.18 a month, plus storage and I/O. The same tool at a steady 4 DCUs around the clock would cost $236.74, more than a db.r6g.large; serverless is cheapest for workloads that are quiet most of the time.

Example 5: an Elastic Cluster. Two shards with two nodes each and 2 vCPUs per node, 500 GB of data: 8 vCPUs x 730 hours x $0.132 = $770.88 compute + $150 storage = $920.88 a month.

Quick monthly estimates for common setups (720 hours, Standard storage unless noted, before data transfer):

Setup	Instances	Storage and I/O (example)	About per month
Development	1 x db.t4g.medium	20 GB, 10M I/Os	$58
Small production	2 x db.r6g.large	100 GB, 200M I/Os	$429
Standard production	3 x db.r6g.large	200 GB, 500M I/Os	$688
Busy production, I/O-Optimized	3 x db.r6g.2xlarge	1 TB, I/O included	$2,808
Spiky internal tool	Serverless, 720 DCU-hours	10 GB, 20M I/Os	$64

The instance line dominates almost every DocumentDB bill, so the biggest levers are instance size, the number of replicas, and turning off what is idle, not storage tricks. The AWS Pricing Calculator has a DocumentDB section for exact figures in other Regions.

Example 6: the forgotten trial. A db.r6g.large created "just to test" and left running with one replica costs $378.94 a month for nothing. A billing alert and a tag with an owner and an end date catch it.

DocumentDB Serverless

DocumentDB Serverless replaces fixed instance sizes with capacity that follows your load, measured in DocumentDB Capacity Units (DCUs, about 2 GiB of memory each with matching CPU). You set a minimum and maximum per cluster, from 0.5 to 256 DCUs, and each serverless instance scales up and down in 0.5 DCU steps within seconds, billed per second at $0.0822 per DCU-hour.

• No scale to zero: the minimum is 0.5 DCU, so an idle serverless instance still costs about $29.59 a month. For environments that sit unused for days, stopping the cluster is cheaper.
• Mix and match: a cluster can combine serverless and provisioned instances, for example a provisioned primary for steady writes and serverless readers for bursty reads, with up to 15 replicas.
• When it fits: development and test, internal tools, new apps with unknown traffic, and workloads with big daily peaks. Steady, busy workloads are usually cheaper on provisioned instances.
• Set the maximum carefully: it caps both performance and cost; a runaway query can otherwise scale you up to the limit.

DocumentDB Elastic Clusters

Elastic Clusters are DocumentDB's sharded option, for workloads beyond one primary instance: millions of writes per second and up to petabytes of data. Data is split across up to 32 shards by a shard key you choose, each shard with up to 64 vCPUs and its own replicas, up to 4 PiB per cluster when data is evenly distributed. You can add shards or change vCPUs per shard later, and the cluster rebalances.

Choose a shard key with many distinct values that spreads both data and traffic evenly (a customer ID, an order ID); a poor key creates a hot shard that limits the whole cluster. Elastic Clusters use their own pricing (per vCPU-hour), support most of the same MongoDB API, and suit large SaaS platforms, gaming, and high-volume event data. Most applications never need them: a single instance-based cluster with read replicas handles a lot.

Global clusters, high availability and backups

• High availability: put replicas in at least two other Availability Zones. If the primary fails, a replica takes over automatically and the cluster endpoint follows. Use the promotion tier setting to choose which replica is promoted first.
• Global clusters: one primary Region replicates to secondary Regions with typical lag under a second, for low-latency reads near users and disaster recovery. In a regional outage, you promote a secondary Region to take writes.
• Backups: continuous backups with point-in-time restore anywhere in a 1 to 35 day window, plus manual snapshots you keep as long as you like and can copy to other Regions or accounts. AWS Backup can manage DocumentDB snapshots alongside the rest of your backups. A restore always creates a new cluster.
• Change streams: a time-ordered feed of inserts, updates and deletes (kept up to 7 days), for triggering Lambda functions, syncing to search or analytics, or building event-driven features.

Create a DocumentDB cluster, step by step

1. Prepare the network: DocumentDB lives in private subnets in at least two Availability Zones. Create a subnet group with those subnets, and a security group that allows TCP port 27017 only from your application's security group.
2. Open DocumentDB in the console and choose Create.
3. Cluster type: choose Instance-based cluster (most apps), or Elastic Cluster for sharding.
4. Configuration: engine version (8.0 for new clusters unless your app needs an older one), instance class (db.t4g.medium for development, db.r6g or db.r8g for production, or Serverless), and the number of instances (one primary plus at least one replica for production).
5. Storage: choose Standard or I/O-Optimized.
6. Authentication: set a master username and password, ideally managed in Secrets Manager so it can be rotated.
7. Advanced settings: pick the VPC, subnet group and security group, keep encryption at rest on (with your KMS key if you need control of it), set the backup retention (7 days is a sensible start), and enable audit logs and profiler logs to CloudWatch if you need them.
8. Create the cluster; it is ready in about ten minutes. Copy the cluster endpoint and the connection string from the cluster's Connectivity tab.

# The same with the AWS CLI (password from an environment variable)
aws docdb create-db-cluster --db-cluster-identifier store-docdb --engine docdb \
  --engine-version 8.0.0 --master-username storeadmin --master-user-password "$DOCDB_PASSWORD" \
  --db-subnet-group-name store-private --vpc-security-group-ids sg-0a1b2c3d4e5f67890 \
  --storage-type iopt1 --backup-retention-period 7 --storage-encrypted

aws docdb create-db-instance --db-instance-identifier store-docdb-1 \
  --db-instance-class db.r6g.large --engine docdb --db-cluster-identifier store-docdb

aws docdb create-db-instance --db-instance-identifier store-docdb-2 \
  --db-instance-class db.r6g.large --engine docdb --db-cluster-identifier store-docdb

For instance types: db.t4g.medium (4 GiB) is fine for development but allows only 30 open cursors and 102 active connections, which busy apps exhaust quickly; db.r6g (Graviton2) and db.r8g (Graviton4) are the production choices, from 16 GiB on the large size; db.r6gd adds local NVMe storage for caching larger working sets. Choose by memory first: performance is best when your working set (frequently used documents and indexes) fits in memory.

Connecting to DocumentDB: mongosh, Compass, Python and from your laptop

Three rules cover most connection problems: connect from inside the VPC (DocumentDB has no public endpoint), use TLS with the AWS certificate bundle (TLS is on by default), and add retryWrites=false, because DocumentDB does not support retryable writes. From an EC2 instance or container in the same VPC:

# Download the certificate bundle once
wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

# mongosh prompts for the password
mongosh "mongodb://store-docdb.cluster-c1abcdefghij.us-east-1.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false" \
  --username storeadmin --password

Python with pymongo:

import os
from pymongo import MongoClient

client = MongoClient(
    "mongodb://store-docdb.cluster-c1abcdefghij.us-east-1.docdb.amazonaws.com:27017/",
    username="storeadmin", password=os.environ["DOCDB_PASSWORD"],
    tls=True, tlsCAFile="global-bundle.pem",
    replicaSet="rs0", readPreference="secondaryPreferred", retryWrites=False,
)
products = client.shop.products
products.insert_one({"sku": "SOFA-3S-GRY", "name": "Aalborg 3-seat", "seats": 3,
                     "fabric": {"color": "gray", "type": "linen"}, "price": 899})
products.create_index("fabric.color")
print(products.find_one({"fabric.color": "gray", "seats": {"$gte": 3}}))

From your laptop (Compass, mongosh or a GUI tool): the cluster is not reachable from the internet, so open a tunnel through something inside the VPC:

# Option 1: Session Manager port forwarding through an EC2 instance (no SSH key or open port 22)
aws ssm start-session --target i-0123456789abcdef0 \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters "host=store-docdb.cluster-c1abcdefghij.us-east-1.docdb.amazonaws.com,portNumber=27017,localPortNumber=27017"

# Option 2: an SSH tunnel through a bastion host
ssh -i bastion-key.pem -N -L 27017:store-docdb.cluster-c1abcdefghij.us-east-1.docdb.amazonaws.com:27017 ec2-user@bastion.example.com

# Then connect to localhost; the certificate name will not match, so allow it for the tunnel only
mongosh "mongodb://localhost:27017/?tls=true&tlsCAFile=global-bundle.pem&tlsAllowInvalidHostnames=true&directConnection=true&retryWrites=false" --username storeadmin --password

In MongoDB Compass, use the same localhost connection string while the tunnel is open, and set the TLS certificate file in the connection options. For a team, AWS Client VPN into the VPC is tidier than individual tunnels. Applications on Lambda need to run in the VPC (with the function in the same private subnets) to reach the cluster; see our Lambda explainer.

Migrating from MongoDB to DocumentDB

1. Check compatibility: run AWS's open-source compatibility tool against your application's logs or source code; it lists any MongoDB operators and stages your app uses that DocumentDB does not support.
2. Pick the target version: DocumentDB 8.0 for new migrations (it also accepts MongoDB 6.0 and 7.0 drivers), or 5.0 if your tested setup needs it.
3. Size the cluster by memory: enough for your working set and indexes, with at least one replica.
4. Copy the data: for small databases, mongodump and mongorestore during a short maintenance window; for large or always-on databases, AWS DMS with a full load followed by ongoing change data capture, so the old and new databases stay in sync until cutover.
5. Rebuild indexes and test: run your test suite and real queries against DocumentDB, compare results and timings, and check the explain plans of slow queries.
6. Cut over: stop writes, let DMS catch up, switch the connection string (adding TLS and retryWrites=false), and keep the old database read-only for a while as a fallback.

The store's catalog moved with mongodump and mongorestore in 20 minutes on a Sunday night. The one surprise was a $where query in the admin search, which DocumentDB does not support; the agency rewrote it as a normal filter in an hour.

Vector search, compatibility and versions

• Vector search for RAG: DocumentDB stores vector embeddings next to your documents and searches them by similarity with HNSW or IVFFlat indexes, so a product catalog or knowledge base can answer "find items like this" or supply context to a language model without a separate vector database. Version 8.0 adds the $vectorSearch stage and parallel index builds up to 30 times faster.
• Versions: DocumentDB supports MongoDB 4.0, 5.0 and 8.0 compatibility; 3.6 is in paid Extended Support. Version 8.0 brings up to 7 times faster queries and up to 5 times better compression, collation and views, new aggregation stages such as $merge, $set, $unset, $bucket and $replaceWith, text index v2, and 256 TiB clusters; it requires TLS 1.2 or later.
• Transactions: multi-document ACID transactions across collections and databases, since version 4.0.
• Client-side field level encryption from version 5.0, for encrypting sensitive fields before they leave the application.
• Not supported or different: some operators and stages (for example $where and map-reduce), some index types and server commands. The supported APIs list in the documentation is the authority; check it against your code.
• BI tools: JDBC and ODBC drivers let Tableau, Power BI and other SQL-based tools query DocumentDB.

A vector search example. Store an embedding (from a model on Bedrock, for example) in each product document, create a vector index, and query by similarity:

db.products.createIndex(
  { embedding: "vector" },
  { name: "product_vectors",
    vectorOptions: { type: "hnsw", dimensions: 1024, similarity: "cosine", m: 16, efConstruction: 64 } }
)

db.products.aggregate([
  { $search: { vectorSearch: { vector: queryEmbedding, path: "embedding", similarity: "cosine", k: 5 } } },
  { $project: { name: 1, price: 1, _id: 0 } }
])

HNSW indexes give fast, accurate searches at the cost of a slower build and more memory; IVFFlat builds faster and uses less memory, with slightly lower recall. For retrieval-augmented generation, the query embedding comes from the user's question, the top matches go into the prompt, and the documents' normal fields (price, stock, category) can filter the results in the same pipeline. Keeping vectors next to the data they describe avoids syncing a separate vector store, which is the main reason to use DocumentDB for this rather than a dedicated vector database.

DocumentDB with Lambda and change streams

Lambda can read a DocumentDB change stream through an event source mapping: turn on change streams for a collection (db.adminCommand({modifyChangeStreams: 1, database: "shop", collection: "orders", enable: true})), create the mapping with the cluster ARN, the database and collection, and a Secrets Manager secret holding the database credentials, and your function receives batches of inserts, updates and deletes in order. The function must run in the cluster's VPC, and the mapping's timeout limit is 14 minutes per invocation. The store uses it to send a confirmation email the moment an order document is inserted, and to push stock changes to the website cache.

Applications in Lambda that query DocumentDB directly should create the MongoDB client outside the handler so connections are reused between invocations, and keep the pool small: a burst of a few hundred concurrent functions can otherwise exhaust a small instance's connection limit.

Monitoring DocumentDB

• CloudWatch metrics per instance and cluster: CPUUtilization, FreeableMemory, BufferCacheHitRatio (aim for close to 100 percent), DatabaseConnections, DatabaseCursors, read and write latency and IOPS, DBClusterReplicaLagMaximum and, on Standard storage, VolumeReadIOPs and VolumeWriteIOPs, which drive the I/O bill.
• Performance Insights shows which queries and wait events use the most database load, the fastest way to find the one slow query behind a busy CPU.
• Profiler logs operations slower than a threshold you set to CloudWatch Logs; audit logs record security-relevant events.
• Alarms worth setting on day one: CPU above 80 percent, free memory low, connections near the instance limit, replica lag above a few seconds, and an AWS Budgets alert for the monthly cost.

Engine versions and in-place upgrades

Each cluster runs one engine version (3.6, 4.0, 5.0 or 8.0), shown in the console and returned by describe-db-clusters. Minor versions within a major version are applied as patches during maintenance windows. For major versions, DocumentDB offers an in-place major version upgrade: from 3.6 or 4.0 to 5.0, and, since April 2026, from 5.0 to 8.0. It keeps the same endpoints, storage and tags, and costs nothing, but there are rules:

• Downtime: the cluster is unavailable during the upgrade and restarts several times, so schedule a maintenance window.
• No downgrade: take a manual snapshot first; if the upgrade causes problems, restore that snapshot to a new cluster.
• Not for global or elastic clusters: for a global cluster, detach the secondary Regions, upgrade the primary, and rebuild the global cluster.
• Instance classes: db.r4 instances must be replaced first, because versions 4.0 and later do not support them.
• Behavior changes: on 8.0, collation is on by default for new collections and indexes, new text indexes use version 2, and the newer query planner is the default; test your queries on a restored copy before upgrading production.

The alternative, for zero-downtime upgrades, is to create a new cluster on the target version and migrate with AWS DMS change data capture, then switch the connection string.

Security and encryption

• Network isolation: the cluster is reachable only inside its VPC; security groups decide which apps can connect on port 27017.
• Encryption in transit: TLS is enabled by default (keep it on; security checks such as "DocumentDB clusters should be encrypted in transit" flag clusters that turn it off), and version 8.0 requires TLS 1.2 or later.
• Encryption at rest: with KMS, covering storage, backups, snapshots and replicas; it must be chosen when the cluster is created.
• Authentication: database users with role-based access control, and IAM authentication for users and roles, so applications can connect with temporary AWS credentials instead of stored passwords.
• Role-based access control (RBAC): built-in roles such as read, readWrite, dbAdmin, userAdmin and clusterAdmin, plus your own roles scoped to specific databases and collections. Give each application its own user with only the roles it needs, and keep the master user for administration.
• Auditing: audit logs of authentication, DDL and user management events (and optionally reads and writes) to CloudWatch Logs.

DocumentDB limits and quotas

• Cluster size: 128 TiB (256 TiB on version 8.0); a single collection up to 32 TiB.
• Documents: up to 16 MiB each, nested up to 200 levels.
• Indexes: 64 per collection, 32 keys in a compound index, 2,048-byte index keys.
• Replicas: up to 15 per cluster.
• Per account per Region: 40 clusters and 40 instances by default; 20 Elastic Clusters with 1,024 vCPUs in total.
• Connections: 1,000 on db.t3 and db.t4g.medium, 3,400 on a .large R instance, up to 60,000 on the biggest; open cursors from 30 (t-class) to thousands on large instances.
• Collections and databases: up to 100,000 of each per cluster; up to 500 stages in an aggregation pipeline.

Common DocumentDB errors and fixes

• Connection timed out or "server selection timeout": you are connecting from outside the VPC, the security group does not allow port 27017 from your client, or the client is in a subnet with no route to the cluster's subnets. DocumentDB cannot be made public; use an instance in the VPC, Session Manager, a bastion tunnel or a VPN.
• "Retryable writes are not supported": add retryWrites=false to the connection string or the client options. Many drivers turn retryable writes on by default.
• SSL or certificate verify failed: the client is not using the AWS certificate bundle (tlsCAFile=global-bundle.pem), the file path is wrong, or, through a tunnel to localhost, the hostname check fails (add tlsAllowInvalidHostnames=true for the tunnel only).
• Authentication failed: wrong username or password, or special characters in the password that are not URL-encoded in the connection string. Master passwords cannot contain /, " or @.
• "Feature not supported" or an unknown operator: your query uses something DocumentDB does not implement; check the supported APIs list and rewrite the query.
• Too many connections or cursor limit reached: each instance size has fixed limits (only 30 cursors on t-class instances). Use connection pooling, close cursors, or move to a bigger instance; watch DatabaseConnectionsMax and DatabaseCursorsMax in CloudWatch.
• Slow queries: missing indexes or a working set larger than memory. Use explain(), enable the profiler, add indexes for your filters and sorts, and size up memory if BufferCacheHitRatio falls.
• Writes fail after a failover: the app pinned an instance endpoint; always connect with the cluster endpoint and replicaSet=rs0 so the driver finds the new primary.
• Unexpected bill: high I/O on Standard storage (consider I/O-Optimized), T-instance CPU credit charges, or forgotten clusters and replicas.

Best practices

• Start on version 8.0 for new clusters, and plan upgrades off 3.6 to avoid Extended Support charges.
• Run at least two instances in different AZs for production, and connect with the cluster endpoint.
• Send reads to replicas with readPreference=secondaryPreferred when slightly stale reads are acceptable.
• Size by memory, keep the working set and indexes in RAM, and index every frequent query.
• Compare Standard and I/O-Optimized after a month of real traffic; switch if I/O is above about 25 percent of the bill.
• Stop development clusters when idle, and tag everything with an owner.
• Test restores, not just backups: restore to a new cluster every quarter and check the data.
• Cache hot reads with ElastiCache when the same product pages are read thousands of times a minute.

Frequently asked questions

The shop has been on DocumentDB for a month: two db.r6g.large instances in different Availability Zones, I/O-Optimized storage, seven days of point-in-time backups, and a catalog that loads faster than before because the working set finally fits in memory. The bill was $477. During a Saturday sale, AWS replaced the primary's host in a routine maintenance event, the replica took over in seconds, and nobody noticed except Ethan, who read about it in an email. Jake asked whether that meant nothing could ever go wrong. "It means a disk failing isn't our problem anymore," Ethan said. "Our own code still is."

Revision note. Written October 21, 2026. Prices are US East (N. Virginia) list prices on that date. We will update this page when DocumentDB prices or features change.