AWS Database Blog

Ramping up on HAQM DocumentDB (with MongoDB compatibility)

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

HAQM DocumentDB (with MongoDB compatibility) is a fast, scalable, highly available, and fully managed document database service that supports MongoDB workloads. As a document database, HAQM DocumentDB makes it easy to store, query, and index JSON data. HAQM 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 HAQM 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 HAQM DocumentDB:

What is HAQM DocumentDB?

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

    • HAQM 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 HAQM DocumentDB solves specific customer problems related to managing and scaling document databases. The highlight of the session is how Fulfillment by HAQM (FBA) reduced their database infrastructure footprint from 96 instances of their previous solution to just two HAQM DocumentDB instances. Migrating to HAQM 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 HAQM 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 HAQM DocumentDB with a SQL interface using the new federated query capabilities in HAQM Athena.
  • Features
    As a fully managed database service, HAQM 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 HAQM DocumentDB. FAQs include What does “MongoDB-compatible” mean?, Does HAQM DocumentDB have an SLA?, How does per-second billing work?, and more.

How to get started with HAQM DocumentDB?

Interested in getting to “hello world” with HAQM 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 HAQM 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 HAQM 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 (HAQM Linux or Ubuntu) so that you can install mongo shell or any MongoDB SDK and connect to HAQM DocumentDB.
  • Connecting from outside a VPC
    HAQM DocumentDB clusters are deployed within an HAQM Virtual Private Cloud (HAQM VPC). Clusters can be accessed directly by HAQM EC2 instances or other AWS services that are deployed in the same HAQM 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 HAQM DocumentDB?

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

    • Best practices
      Learn best practices for working with HAQM DocumentDB. This section is continually updated as new best practices are identified.
    • Monitoring
      HAQM DocumentDB provides HAQM 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 HAQM 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, HAQM 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
      HAQM 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 HAQM S3, which is designed for 99.999999999% durability. HAQM DocumentDB backups are automatic, incremental, and continuous and have no impact on cluster performance.
    • Security
      HAQM DocumentDB allows you to encrypt your databases using keys you create and control through AWS Key Management Service (KMS). On a cluster running with HAQM 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 HAQM DocumentDB are encrypted-in-transit with TLS.
    • Pricing and the Pricing Calculator
      There are no upfront investments required to use HAQM DocumentDB, and you only pay for the capacity they use. HAQM DocumentDB charges on four dimensions: instance, storage, IOPS, and backup storage.
  • High Availability and Replication
    You can achieve high availability and read scaling in HAQM DocumentDB by using replica instances. The health of your HAQM DocumentDB cluster and its instances are continuously monitored. On instance failure, HAQM DocumentDB automates failover to a replica. HAQM 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 HAQM 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 HAQM EC2 to HAQM 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 HAQM DocumentDB.

In the three-minute video below, learn how to perform a live migration from MongoDB to HAQM DocumentDB using the AWS DMS. In this video, I set up two identical applications running against MongoDB (source) and HAQM 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 HAQM 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 HAQM DocumentDB.
    • Migration overview (from re:Invent 2019)
      Jeff Duffy, the senior specialist solutions architect for HAQM DocumentDB, provides an overview of customers’ strategies and considerations when migrating to HAQM 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 HAQM DocumentDB. With HAQM 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 HAQM DocumentDB met their high SLA and security requirements.

Who is using HAQM DocumentDB?

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

    • Learn how Fulfillment by HAQM uses HAQM DocumentDB
      Learn how Fulfillment by HAQM (FBA) reduced their database infrastructure footprint from 96 instances of their previous solution to just two HAQM DocumentDB instances. Migrating to HAQM 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 HAQM DocumentDB.
    • Learn how FINRA migrated from Oracle to HAQM DocumentDB
      Learn how FINRA migrated from a relational database using XML to HAQM DocumentDB. With HAQM 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 HAQM DocumentDB met their high SLA and security requirements.
  • Deutsche Fußball Liga GmbH (DFL) uses AWS and HAQM 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 HAQM 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 HAQM 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 HAQM DocumentDB?

About the Authors

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

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