AWS Database Blog

Ramping up on Amazon DocumentDB (with MongoDB compatibility)

This blog post was last reviewed and updated February, 2022.

Amazon DocumentDB (with MongoDB compatibility) is a fast, scalable, highly available, and fully managed document database service that supports MongoDB workloads. As a document database, Amazon DocumentDB makes it easy to store, query, and index JSON data. Amazon DocumentDB is compatible with MongoDB 3.6, 4.0 or 5.0 drivers and tools. A vast majority of the applications, drivers, and tools that you already use today with their MongoDB database can be used with Amazon DocumentDB with little or no change.

In this blog post, I provide you with a quick summary and set of resources, to the topics that I get asked about the most, so that you can quickly ramp up on Amazon DocumentDB:

What is Amazon DocumentDB?

To learn more about what makes Amazon DocumentDB unique and how its cloud-native architecture leverages the separation of storage and compute to help you scale quickly, visit the following resources:

    • Amazon DocumentDB Deep Dive (from re:Invent 2019)
      In this talk, I give an overview of why developers choose the document model, common use cases, examples of when you should consider an alternative data store, and how Amazon DocumentDB solves specific customer problems related to managing and scaling document databases. The highlight of the session is how Fulfillment by Amazon (FBA) reduced their database infrastructure footprint from 96 instances of their previous solution to just two Amazon DocumentDB instances. Migrating to Amazon DocumentDB simultaneously increased performance by 66 percent and reduced costs by 45 percent. FBA’s example shows the result of using the right database for the job. FBA also provides a great set of lessons learned for scaling reads and writes, and indexing strategies with Amazon DocumentDB. The talk also includes three live demos where I create a snapshot backup of a 1.5-TB cluster in less than one minute, add a new instance to the same 1.5-TB cluster in five minutes, and query data in Amazon DocumentDB with a SQL interface using the new federated query capabilities in Amazon Athena.
  • Features
    As a fully managed database service, Amazon DocumentDB provides a number of capabilities and features that enable you to build performant, scalable, secure and compliant, and highly available applications on AWS.
  • FAQs
    The most frequently asked questions for Amazon DocumentDB. FAQs include What does “MongoDB-compatible” mean?, Does Amazon DocumentDB have an SLA?, How does per-second billing work?, and more.

How to get started with Amazon DocumentDB?

Interested in getting to “hello world” with Amazon DocumentDB? Visit the following guides and documentation for more information:

    • Getting started guide
      Go from zero to “Hello World’ with the getting started guide. Learn how to provision an Amazon DocumentDB cluster using the AWS Management Console or AWS CLI and connect and query using the mongo shell.
    • Connecting from AWS Cloud9
      For development, test, and management, you can use AWS Cloud9 to connect to and access your Amazon DocumentDB cluster from your web browser. AWS Cloud9 is a cloud-based integrated development environment (IDE) that lets you write, run, and debug your code using just a browser. It provides a web-based terminal access (Amazon Linux or Ubuntu) so that you can install mongo shell or any MongoDB SDK and connect to Amazon DocumentDB.
  • Connecting from outside a VPC
    Amazon DocumentDB clusters are deployed within an Amazon Virtual Private Cloud (Amazon VPC). Clusters can be accessed directly by Amazon EC2 instances or other AWS services that are deployed in the same Amazon VPC. Additionally, clusters can be accessed by EC2 instances or other AWS services in different VPCs in the same AWS Region or other Regions via VPC peering.

How to build and scale with Amazon DocumentDB?

When you are ready to starting building and scaling on Amazon DocumentDB, below are the key resources that you are going to want to start with.

    • Best practices
      Learn best practices for working with Amazon DocumentDB. This section is continually updated as new best practices are identified.
    • Monitoring
      Amazon DocumentDB provides Amazon CloudWatch metrics for your cluster and instances. You can use the AWS Management Console to view over 20 key operational metrics for your cluster, including compute, memory, storage, query throughput, and active connections. Additionally, you can use the profiler in Amazon DocumentDB to log the execution time and details of operations that were performed on your cluster. The profiler is useful for monitoring the slowest operations on your cluster to help you improve individual query performance and overall cluster performance.
    • Read scaling
      Unlike traditional monolithic database architecture, Amazon DocumentDB separates storage and compute. Given this modern architecture, we encourage you to read scale on replica instances. Reads on replica instances do not block writes being replicated from the primary instance. You can add up to 15 read replica instances in a cluster and scale out to millions of reads per second.
    • Backup and PITR restore
      Amazon DocumentDB’s backup capability enables point-in-time recovery for your clusters. This allows you to restore your cluster to any second during your retention period, up until the last five minutes. Your automatic backup retention period can be configured up to thirty-five days. Automated backups are stored in Amazon S3, which is designed for 99.999999999% durability. Amazon DocumentDB backups are automatic, incremental, and continuous and have no impact on cluster performance.
    • Security
      Amazon DocumentDB allows you to encrypt your databases using keys you create and control 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 the automated backups, snapshots, and replicas in the same cluster. By default, connections between a client and Amazon DocumentDB are encrypted-in-transit with TLS.
    • Pricing and the Pricing Calculator
      There are no upfront investments required to use Amazon DocumentDB, and you only pay for the capacity they use. Amazon DocumentDB charges on four dimensions: instance, storage, IOPS, and backup storage.
  • High Availability and Replication
    You can achieve high availability and read scaling in Amazon DocumentDB by using replica instances. The health of your Amazon DocumentDB cluster and its instances are continuously monitored. On instance failure, Amazon DocumentDB automates failover to a replica. Amazon DocumentDB recovery does not require the potentially lengthy replay of database redo logs, so your instance restart times are typically 30 seconds or less. It also isolates the database cache from database processes, allowing the cache to survive a database restart.

How to migrate to Amazon DocumentDB?

Many developers are looking to get out of the business of investing in undifferentiated heavy lifting and self-managing their databases. You migrate your MongoDB databases on-premises or on Amazon EC2 to Amazon DocumentDB with virtually no downtime using the AWS Database Migration Service (DMS). With DMS, you can migrate from a MongoDB replica set or from a sharded cluster to Amazon DocumentDB.

In the three-minute video below, learn how to perform a live migration from MongoDB to Amazon DocumentDB using the AWS DMS. In this video, I set up two identical applications running against MongoDB (source) and Amazon DocumentDB (target), create a DMS task for a live migration, make changes to the source application, and then verify the live migration with the target application.

To perform migrations, you typically use the AWS DMS to perform online, hybrid, or offline migrations. To learn more about migrations, visit the following:

    • Migration guide
      The Amazon DocumentDB migration guide walks you through all the phases – discovery, planning, testing, failover – that you need to consider for a migration. The guide also discusses different approaches (online, hybrid, offline) and tools like DMS that help you migrate to Amazon DocumentDB.
    • Migration overview (from re:Invent 2019)
      Jeff Duffy, the senior specialist solutions architect for Amazon DocumentDB, provides an overview of customers’ strategies and considerations when migrating to Amazon DocumentDB. The session includes discussions about relational and nonrelational sources, migration phases of discovery/planning/testing/execution, cluster sizing, and migration tooling. The highlight of the session is FINRA’s story of how they migrated from a relational database using XML to Amazon DocumentDB. With Amazon DocumentDB, FINRA can move faster using JSON natively in their database because there is no transformation layer needed from the application. FINRA also discusses how Amazon DocumentDB met their high SLA and security requirements.

Who is using Amazon DocumentDB?

Customers like Capital One, OnDeck, Freshop, Woot!, Amazon and many more are using Amazon DocumentDB to build and scale their applications on AWS. To learn more about customers using Amazon DocumentDB, visit the following:

    • Learn how Fulfillment by Amazon uses Amazon DocumentDB
      Learn how Fulfillment by Amazon (FBA) reduced their database infrastructure footprint from 96 instances of their previous solution to just two Amazon DocumentDB instances. Migrating to Amazon DocumentDB simultaneously increased performance by 66 percent and reduced costs by 45 percent. FBA’s example shows the result of using the right database for the job. FBA also provides a great set of lessons learned for scaling reads and writes, and indexing strategies with Amazon DocumentDB.
    • Learn how FINRA migrated from Oracle to Amazon DocumentDB
      Learn how FINRA migrated from a relational database using XML to Amazon DocumentDB. With Amazon DocumentDB, FINRA can move faster using JSON natively in their database because there is no transformation layer needed from the application. FINRA also discusses how Amazon DocumentDB met their high SLA and security requirements.
  • Deutsche Fußball Liga GmbH (DFL) uses AWS and Amazon DocumentDB their publishing platform
    “We, the Deutsche Fußball Liga GmbH (DFL) use AWS to power our publishing platform, delivering the latest news from the league to millions of fans worldwide. As our content and user base grew, we had a focus on maintaining our relational database’s performance. We migrated to Amazon DocumentDB (with MongoDB compatibility) because of its flexible schema, native JSON support that enables our developers to deploy faster, and its decoupled architecture can scale our read throughput in minutes. We prototyped the application locally using the MongoDB Community Edition, and quickly deployed to production on Amazon DocumentDB. Everything worked just as we expected and we have successfully scaled our database performance.” -Andreas Heyden, CEO DFL Digital Sports, EVP Digital Innovations – DFL Group

How to stay up to date with Amazon DocumentDB?

About the Authors

Joseph Idziorek is a Principal Product Manager at Amazon Web Services.

Sameer Kumar is a Senior Specialist Technical Account Manager at Amazon Web Services. He focuses on Amazon RDS PostgreSQL, Aurora PostgreSQL and DocumentDB. He works with enterprise customers providing technical assistance on database operational performance and sharing database best practices.