What is Amazon DocumentDB (with MongoDB compatibility)?

Amazon DocumentDB (with MongoDB compatibility) is a fast, scalable, highly available, and fully managed enterprise document database service that supports native JSON workloads. As a document database, Amazon DocumentDB makes it easy to store, query, and index JSON data. Developers can use the same MongoDB application code, drivers, and tools as they do today to run, manage, and scale workloads on Amazon DocumentDB. Enjoy improved performance, scalability, and availability without worrying about managing the underlying infrastructure.

Customers can use AWS Database Migration Service (DMS) to easily migrate their on-premises or Amazon Elastic Compute Cloud (EC2) MongoDB non-relational databases to Amazon DocumentDB with virtually no downtime. There are no upfront investments required to use Amazon DocumentDB, and customers only pay for the capacity they use.

What use cases are well-suited for a document database like Amazon DocumentDB?

Document-oriented databases are one of the fastest growing categories of noSQL databases, with the primary reason being that document databases offer both flexible schemas and extensive query capabilities. The document model is a great choice for use cases with dynamic datasets that require ad-hoc querying, indexing, and aggregations. With the scale that Amazon DocumentDB provides, it is used by a wide variety of customers for use cases such as content management, personalization, catalogs, mobile and web applications, IoT, and profile management.

What does "MongoDB-compatible" mean?

MongoDB compatible” means that Amazon DocumentDB interacts with the Apache 2.0 open source MongoDB 3.6, 4.0, and 5.0 APIs. As a result, you can use the same MongoDB drivers, applications, and tools with Amazon DocumentDB with little or no changes. While Amazon DocumentDB supports a vast majority of the MongoDB APIs that customers actually use, it does not support every MongoDB API. Our focus has been to deliver the capabilities that customer actually use and need.

Since launch, we have continued to work backwards from customers and have delivered an additional 80+ capabilities, including MongoDB 4.0 and 5.0 compatibility, transactions, and sharding. To learn more about the supported MongoDB APIs, see the compatibility documentation. To learn more about recent Amazon DocumentDB launches, see “Amazon DocumentDB Announcements” on the Amazon DocumentDB resources page.

Is Amazon DocumentDB restricted by the MongoDB SSPL license?

No. Amazon DocumentDB does not utilize any MongoDB SSPL code and thus is not restricted by this license. Instead, Amazon DocumentDB interacts with the Apache 2.0 open-source MongoDB 3.6, 4.0, and 5.0 APIs. We will continue to listen and work backward from our customers to deliver the capabilities that they need. To learn more about the supported MongoDB APIs, see the compatibility documentation. To learn more about recent Amazon DocumentDB launches, see “Amazon DocumentDB Announcements” on the Amazon DocumentDB resources page.

How can I migrate data from an existing MongoDB database to Amazon DocumentDB?

Customers can use AWS Database Migration Service (DMS) to easily migrate their on-premises or Amazon Elastic Compute Cloud (EC2) MongoDB databases to Amazon DocumentDB with virtually no downtime. With DMS, you can migrate from a MongoDB replica set or from a sharded cluster to Amazon DocumentDB. Additionally, you can use most existing tools to migrate data from a MongoDB database to Amazon DocumentDB, including mongodump/mongorestore, mongoexport/mongoimport, and third-party tools that support Change Data Capture (CDC) via the oplog. For more information, see Migrating to Amazon DocumentDB.

Do I need to change client drivers to use Amazon DocumentDB?

No, Amazon DocumentDB works with a vast majority of MongoDB drivers compatible with MongoDB 3.4+.

Does Amazon DocumentDB support ACID transactions?

Yes. With the launch of support for MongoDB 4.0 compatibility, Amazon DocumentDB supports the ability to perform atomicity, consistency, isolation, durability (ACID) transactions across multiple documents, statements, collections, and databases.

Is Amazon DocumentDB subject to MongoDB's end of life (EOL) schedule?

No, Amazon DocumentDB does not follow the same support lifecycles as MongoDB and MongoDB's EOL schedule does not apply to Amazon DocumentDB.

How do I access my Amazon DocumentDB cluster?

Amazon DocumentDB clusters are deployed within a customer's Amazon VPC (VPC) and can be accessed directly by Amazon Elastic Compute Cloud (EC2) instances or other AWS services that are deployed in the same VPC. Additionally, Amazon DocumentDB can be accessed by Amazon EC2 instances or other AWS services in different VPCs in the same region or other regions via VPC peering. Access to Amazon DocumentDB clusters must be done through the mongo shell or with MongoDB drivers. Amazon DocumentDB requires that you authenticate when connecting to a cluster. For additional options, see Connecting to an Amazon DocumentDB Cluster from Outside an Amazon VPC.

Why are Amazon RDS permissions and resources required to use Amazon DocumentDB?

For certain management features such as instance lifecycle management, encryption-at-rest with Amazon Key Management Service (KMS) keys and security groups management, Amazon DocumentDB leverages operational technology that is shared with Amazon Relational Database Service (RDS) and Amazon Neptune. When using the describe-db-instances and describe-db-clusters AWS CLI APIs, we recommend filtering for Amazon DocumentDB resources using the following parameter: "--filter Name=engine,Values=docdb".

What instances types does Amazon DocumentDB offer?

Please see the Amazon DocumentDB pricing page for current information on available instance types per region.

How do I try Amazon DocumentDB?

To try Amazon DocumentDB, please see the Getting Started guide.

Does Amazon DocumentDB have an SLA?


What type of performance can I expect from Amazon DocumentDB?

When writing to storage, Amazon DocumentDB only persists a write-ahead logs, and does not need to write full buffer page syncs. As a result of this optimization, which does not compromise durability, Amazon DocumentDB writes are typically faster than traditional databases. Amazon DocumentDB clusters can scale out to millions of reads per second with up to 15-read replicas.


How much does Amazon DocumentDB cost and in which AWS regions is Amazon DocumentDB available?

Please see the Amazon DocumentDB pricing page for current information on regions and prices.

Does Amazon DocumentDB have a free tier and can you get started for free?

Yes, you can try Amazon DocumentDB for free using the 1-month free trial. If you have not used Amazon DocumentDB before, you are eligible for a one month free trial. Your organization gets 750 hours per month of t3.medium instance usage, 30 million IOs, 5 GB of storage, and 5 GB of backup storage for free for 30 days. Once your one month free trial expires or your usage exceeds the free allowance, you can shut down your cluster to avoid any charges, or keep it running at our standard on-demand rates. To learn more, refer to the DocumentDB free trial page.

Elastic Clusters

What is Amazon DocumentDB Elastic Clusters?

Amazon DocumentDB Elastic Clusters enables you to elastically scale your document database to handle millions of writes and reads, with petabytes of storage capacity. Elastic Clusters simplifies how customers interact with Amazon DocumentDB by automatically managing the underlying infrastructure and removing the need to create, remove, upgrade, or scale instances.

How do I get started with Elastic Clusters?

You can create an Elastic Clusters cluster using the Amazon DocumentDB API, SDK, CLI, CloudFormation (CFN), or the AWS console. When provisioning your cluster, you specify how many shards and the compute per shard that your workload needs. Once you have created your cluster, you are ready to start leveraging Elastic Clusters’ elastic scalability. Now, you can connect to the Elastic Clusters cluster and read or write data from your application. Elastic Clusters is elastic. Depending on your workload’s needs, you can add or remove compute by modifying your shard count and/or compute per shard using the AWS console, API, CLI, or SDK. Elastic Clusters will automatically provision/de-provision the underlying infrastructure and rebalance your data.

How does Elastic Clusters work?

Elastic Clusters uses sharding to partition data across Amazon DocumentDB’s distributed storage system. Sharding, also known as partitioning, splits large data sets into small data sets across multiple nodes enabling customers to scale out their database beyond vertical scaling limits of a single database. Elastic Clusters utilizes the separation of compute and storage in Amazon DocumentDB. Rather than re-partitioning collections by moving small chunks of data between compute nodes, Elastic Clusters can copy data efficiently within the distributed storage system.

What types of sharding does Elastic Clusters support?

Elastic Clusters supports hash-based partitioning.

How is Elastic Clusters different from MongoDB sharding?

With Elastic Clusters, you can easily scale out or scale in your workload on Amazon DocumentDB typically with little to no application downtime or impact to performance regardless of data size. A similar operation on MongoDB would impact application performance and take hours, and in some cases days. Elastic Clusters also offers differentiated management capabilities such as no impact backups and rapid point in time restore enabling customers to focus more time on their applications rather than managing their database.

Do I need to make any changes to my application to use Elastic Clusters?

No. You do not need to make any changes to your application to use Elastic Clusters.

Can I convert my existing Amazon DocumentDB cluster to an Elastic Clusters cluster?

No, in the near-term, you can leverage AWS Database Migration service (DMS) to migrate data from an existing Amazon DocumentDB cluster to an Elastic Clusters cluster.

How do I define a shard key?

Choosing an optimal shard key for Elastic Clusters is no different than other databases. A great shard key has two characteristics - high frequency and high cardinality. For example, if your application stores user_orders in DocumentDB, then generally you have to retrieve the data by the user. Therefore, you want all orders related to a given user to be in one shard. In this case, user_id would be a good shard key. Read more information

What are the concepts associated with Elastic Clusters?

  • Elastic Clusters: An Amazon DocumentDB cluster that allows you to scale your workload’s throughput to millions of reads/writes per second and storage to petabytes. An Elastic Cluster cluster comprises of one or more shards for compute and a storage volume, and is highly available across multiple Availability Zones by default.
  • Shard: A shard provides compute for Elastic Clusters cluster. A shard by default will have three nodes, one writer node and two reader nodes. You can have a maximum of 32 shards and each shard can have a maximum of 64 vCPUs.
  • Shard key: Shard key is an optional field in your JSON documents that Elastic Clusters uses to distribute read and write traffic to the matching shard. You are advised to pick a key that has lots of unique values. A good shard key will evenly partition your data across the underlying shards, giving your workload the best throughput and performance. 
  • Sharded collection: A collection whose data is distributed across an Elastic Clusters cluster.

How does Elastic Clusters relate to other AWS services?

Elastic Clusters integrates with other AWS services in the same way DocumentDB does today. First, you can use AWS Database Migration Service (DMS) to migrate from MongoDB and other relational databases to Elastic Clusters. Second, you can monitor the health and performance of your Elastic Clusters cluster using Amazon CloudWatch. Third, you can set up authentication and authorization through AWS IAM users and roles and use AWS VPC for secure VPC-only connections. Last, you can use AWS Glue to import and export data from/to other AWS services such as S3, Redshift and OpenSearch.

Can I migrate my existing MongoDB sharded workloads to Elastic Clusters?

Yes. You can migrate your existing MongoDB sharded workloads to Elastic Clusters. You can either use the AWS Database Migration Service or native MongoDB tools, such as mongodump and mongorestore, to migrate your MongoDB workload to Elastic Clusters. Elastic Clusters also supports MongoDB’s commonly used APIs, such as shardCollection(), giving you the flexibility to reuse existing tooling and scripts with Amazon DocumentDB.

Hardware, scaling, and storage

What are the minimum and maximum storage limits of an Amazon DocumentDB cluster?

The minimum storage is 10 GB. Based on your cluster usage, your Amazon DocumentDB storage will automatically grow, up to 128 TiB in 10 GB increments with no impact on performance. With Amazon DocumentDB Elastic Clusters, storage will automatically grow up to 4 PiB in 10 GB increments. For either case, there is no need to provision storage in advance.

How does Amazon DocumentDB scale?

Amazon DocumentDB scales in two dimensions: storage and compute. Amazon DocumentDB's storage automatically scales from 10 GB to 128 TiB in Instance-based Clusters, and up to 4 PiB for Amazon DocumentDB Elastic Clusters. Amazon DocumentDB's compute capacity can be scaled up by creating larger instances and horizontally (for greater read throughput) by adding additional replica instances to the cluster.

How do I scale the compute resources associated with my Amazon DocumentDB cluster?

You can scale the compute resources allocated to your instance in the AWS Management Console by selecting the desired instance and clicking the “modify” button. Memory and CPU resources are modified by changing your instance class.

When you modify your instance class, your requested changes will be applied during your specified maintenance window. Alternatively, you can use the "Apply Immediately" flag to apply your scaling requests immediately. Both of these options will have an availability impact for a few minutes as the scaling operation is performed. Bear in mind that any other pending system changes will also be applied.

Backup and restore

How do I enable backups for my cluster?

Automated backups are always enabled on Amazon DocumentDB clusters. Amazon DocumentDB’s simple database backup capability enables point-in-time recovery for your clusters. You can increase your backup window for point-in-time restores up to 35 days. Backups do not impact database performance.

Can I take cluster snapshots and keep them around as long as I want?

Yes. Manual snapshots can be retained beyond the backup window and there is no performance impact when taking snapshots. Note that restoring data from cluster snapshots requires creating a new cluster.

If my instance fails, what is my recovery path?

Amazon DocumentDB automatically makes your data durable across three Availability Zones (AZs) within a Region and will automatically attempt to recover your instance in a healthy AZ with no data loss. In the unlikely event your data is unavailable within Amazon DocumentDB storage, you can restore from a cluster snapshot or perform a point-in-time restore operation to a new cluster. Note that the latest restorable time for a point-in-time restore operation can be up to five minutes in the past.

What happens to my automated backups and cluster snapshots if I delete my cluster?

You can choose to create a final snapshot when deleting your instance. If you do, you can use this snapshot to restore the deleted instance at a later date. Amazon DocumentDB retains this final user-created snapshot along with all other manually created snapshots after the instance is deleted. Only snapshots are retained after the instance is deleted (i.e., automated backups created for point-in-time restore are not kept).

What happens to my automated backups and cluster snapshots if I delete my account?

Deleting your AWS account will delete all automated backups and snapshot backups contained in the account.

Can I share my snapshots with another AWS account?

Yes. Amazon DocumentDB gives you the ability to create snapshots of your cluster, which you can use later to restore a cluster. You can share a snapshot with a different AWS account, and the owner of the recipient account can use your snapshot to restore a cluster that contains your data. You can even choose to make your snapshots public – that is, anybody can restore a cluster containing your (public) data. You can use this feature to share data between your various environments (production, dev/test, staging, etc.) that have different AWS accounts, as well as keep backups of all your data secure in a separate account in case your main AWS account is ever compromised.

Will I be billed for shared snapshots?

There is no charge for sharing snapshots between accounts. However, you may be charged for the snapshots themselves, as well as any clusters that you restore from shared snapshots.

Can I automatically share snapshots?

We do not support sharing automatic cluster snapshots. To share an automatic snapshot, you must manually create a copy of the snapshot, and then share the copy.

Can I share my Amazon DocumentDB snapshots across different regions?

No. Your shared Amazon DocumentDB snapshots will only be accessible by accounts in the same region as the account that shares them.

Can I share an encrypted Amazon DocumentDB snapshot?

Yes. You can share encrypted Amazon DocumentDB snapshots. The recipient of the shared snapshot must have access to the KMS key that was used to encrypt the snapshot.

Can I use Amazon DocumentDB snapshots outside of the service?

No. Amazon DocumentDB snapshots can only be used inside of the service.

What happens to my backups if I delete my cluster?

You can choose to create a final snapshot when deleting your cluster. If you do, you can use this snapshot to restore the deleted cluster at a later date. Amazon DocumentDB retains this final user-created snapshot along with all other manually created snapshots after the cluster is deleted.

High availability and replication

How does Amazon DocumentDB improve my cluster’s fault tolerance to disk failures?

Amazon DocumentDB automatically divides your storage volume into 10 GB segments spread across many disks. Each 10 GB chunk of your storage volume is replicated six ways, across three Availability Zones (AZs). Amazon DocumentDB is designed to transparently handle the loss of up to two copies of data without affecting write availability and up to three copies without affecting read availability. Amazon DocumentDB’s storage volume is also self-healing. Data blocks and disks are continuously scanned for errors and repaired automatically.

How does Amazon DocumentDB improve recovery time after a database crash?

Unlike other databases, after a database crash, Amazon DocumentDB does not need to replay the redo log from the last database checkpoint (typically five minutes) and confirm that all changes have been applied, before making the database available for operations. This reduces database restart times to less than 60 seconds in most cases. Amazon DocumentDB moves the cache out of the database process and makes it available immediately at restart time. This prevents you from having to throttle access until the cache is repopulated to avoid brownouts.

What kind of replicas does Amazon DocumentDB support?

Amazon DocumentDB supports read replicas, which share the same underlying storage volume as the primary instance. Updates made by the primary instance are visible to all Amazon DocumentDB replicas.

  • Feature: Amazon DocumentDB read replicas
  • Number of replicas: Up to 15
  • Replication Type: Asynchronous (typically milliseconds)
  • Performance impact on primary: Low
  • Act as failover target: Yes (no data loss)
  • Automated failover: Yes

Can I have cross-region replicas with Amazon DocumentDB?

Yes, you can replicate your data across regions using the Global Cluster feature. Global Clusters span across multiple AWS Regions. Global clusters replicate your data to clusters in up to five Regions with little to no impact on performance. Global clusters provide faster recovery from Region-wide outages and enable low-latency global reads. To learn more see our blog post.

Can I prioritize certain replicas as failover targets over others?

Yes. You can assign a promotion priority tier to each instance on your cluster. If the primary instance fails, Amazon DocumentDB will promote the replica with the highest priority to primary. If there are inconsistencies between two or more replicas in the same priority tier, then Amazon DocumentDB will promote the replica that is the same size as the primary instance.

Can I modify priority tiers for instances after they have been created?

You can modify the priority tier for an instance at any time. Simply modifying priority tiers will not trigger a failover.

Can I prevent certain replicas from being promoted to the primary instance?

You can assign lower priority tiers to replicas that you do not want promoted to the primary instance. However, if the higher priority replicas on the cluster are unhealthy or unavailable for some reason, then Amazon DocumentDB will promote the lower priority replica.

How does Amazon DocumentDB assure high availability of my cluster?

Amazon DocumentDB can be deployed in a high-availability configuration by using replica instances in multiple AWS Availability Zones as failover targets. In the event of a primary instance failure, a replica instance is automatically promoted to be the new primary with minimal service interruption.

How can I improve upon the availability of a single Amazon DocumentDB instance?

You can add additional Amazon DocumentDB replicas. Amazon DocumentDB replicas share the same underlying storage as the primary instance. Any Amazon DocumentDB replica can be promoted to become primary without any data loss and therefore can be used for enhancing fault tolerance in the event of a primary instance failure. To increase cluster availability, simply create one to 15 replicas, in multiple AZs, and Amazon DocumentDB will automatically include them in failover primary selection in the event of an instance outage.

What happens during failover and how long does it take?

Failover is automatically handled by Amazon DocumentDB so that your applications can resume database operations as quickly as possible without manual administrative intervention.

  • If you have an Amazon DocumentDB replica instance in the same or a different Availability Zone, when failing over, Amazon DocumentDB flips the canonical name record (CNAME) for your instance to point at the healthy replica, which is in turn promoted to become the new primary. Start-to-finish, failover typically completes within 30 seconds. 
  • If you do not have an Amazon DocumentDB replica instance (i.e. a single instance cluster), Amazon DocumentDB will attempt to create a new instance in the same Availability Zone as the original instance. This replacement of the original instance is done on a best-effort basis and may not succeed, for example, if there is an issue that is broadly affecting the Availability Zone. 

Your application should retry database connections in the event of connection loss.

If I have a primary instance and an Amazon DocumentDB replica instance actively taking read traffic and a failover occurs, what happens?

Amazon DocumentDB will automatically detect a problem with your primary instance and begin routing your read/write traffic to an Amazon DocumentDB replica instance. On average, this failover will complete within 30 seconds. In addition, the read traffic that your Amazon DocumentDB replicas instances were serving will be briefly interrupted.

How far behind the primary will my replicas be?

Since Amazon DocumentDB replicas share the same data volume as the primary instance, there is virtually no replication lag. We typically observe lag times in the 10s of milliseconds.

Security and compliance

Can I use Amazon DocumentDB in Amazon Virtual Private Cloud (Amazon VPC)?

Yes. All Amazon DocumentDB clusters must be created in a VPC. With Amazon VPC, you can define a virtual network topology that closely resembles a traditional network that you might operate in your own datacenter. This gives you complete control over who can access your Amazon DocumentDB clusters.

Does Amazon DocumentDB support role-based access control (RBAC)?

Amazon DocumentDB supports RBAC with built-in roles. RBAC enables you to enforce least privilege as a best practice by restricting the actions that users are authorized to perform. For more information, see Amazon DocumentDB role-based access control.

How do the existing MongoDB authentication modes work with Amazon DocumentDB?

Amazon DocumentDB utilizes VPC’s strict network and authorization boundary. Authentication and authorization for Amazon DocumentDB management APIs is provided by IAM users, roles, and policies. Authentication to an Amazon DocumentDB database are done via standard MongoDB tools and drivers with Salted Challenge Response Authentication Mechanism (SCRAM), the default authentication mechanism for MongoDB.

Does Amazon DocumentDB support encrypting my data-at-rest?

Yes. Amazon DocumentDB allows you to encrypt your clusters using keys you manage through AWS Key Management Service (KMS). On a cluster running with Amazon DocumentDB encryption, data stored at rest in the underlying storage is encrypted, as are its automated backups, snapshots, and replicas in the same cluster. Encryption and decryption are handled seamlessly. For more information about the use of KMS with Amazon DocumentDB, see the Encrypting Amazon DocumentDB Data at Rest.

Can I encrypt an existing unencrypted cluster?

Currently, encrypting an existing unencrypted Amazon DocumentDB cluster is not supported. To use Amazon DocumentDB encryption for an existing unencrypted cluster, create a new cluster with encryption enabled and migrate your data into it.

What compliance certifications does Amazon DocumentDB meet?

Amazon DocumentDB was designed to meet the highest security standards and to make it easy for you to verify our security and meet your own regulatory and compliance obligations. Amazon DocumentDB has been assessed to comply with PCI DSS, ISO 9001, 27001, 27017, and 27018, SOC 1, 2 and 3, and Health Information Trust Alliance (HITRUST) Common Security Framework (CSF) certification, in addition to being HIPAA eligible. AWS compliance reports are available for download in AWS Artifact.

Major version upgrade

What is in-place major version upgrade?

In-place major version upgrade (MVU) lets you upgrade Amazon DocumentDB 3.6 or 4.0 clusters to Amazon DocumentDB 5.0 using the AWS Console, Software Development Kit (SDK), or Command Line Interface (CLI). With in-place MVU, there is no need to create new clusters or change your end points. Except in AWS GovCloud (US) Region, in-place MVU is available in all regions where Amazon DocumentDB 5.0 is available. To get started with in-place MVU, please review in-place MVU documentation.

Why should I use in-place MVU?

In-place MVU lets you seamlessly upgrade your Amazon DocumentDB 3.6 or 4.0 clusters to version 5.0 without the need to perform backup and restore to another cluster and without using other data migration tools. In doing so, it reduces the time and effort associated with usual upgrade process which entail configuring the source and target end points, migrating indexes and data, changing application code, and more.

You won't need to change your endpoint in your applications post upgrade. Since the data stays in the same cluster, there is no additional cost to upgrade using feature.

What is the downtime when upgrading with in-place MVU?

Downtime can vary from cluster to cluster depending on number of collections, indexes, databases, and instances. Before running in-place major version upgrade on your production cluster, we strongly recommend running it in a lower environment to test downtime, performance, and also verify that your applications work as expected post upgrade.

You can also utilize Amazon DocumentDB’s fast clone feature to clone your cluster data for testing. Depending on the complexity of your Amazon DocumentDB implementation, you can engage our database solutions architect for additional help.

What engine versions does in-place MVU support today?

In-place MVU is only supported with Amazon DocumentDB 3.6 or 4.0 as a source and version 5.0 as target. It is not supported for Amazon DocumentDB Global Clusters or Elastic Clusters or with DocumentDB 4.0 as target.

Learn more about pricing

Visit the Amazon DocumentDB (with MongoDB compatibility) pricing page.

Learn more 
Sign up for a free account

Instantly get access to the AWS Free Tier. 

Sign up 
Start building in the console

Get started building with Amazon DocumentDB (with MongoDB compatibility) in the AWS Console.

Sign in