Traditional relational databases store data in strict tables: fixed columns, fixed data types, and every row shaped identically. That works beautifully for accounting ledgers and inventory counts. It works far less beautifully for things like a user profile, a product catalog entry, or a chat message thread, where different records naturally carry different fields, nested lists, and optional attachments. Forcing that kind of data into rigid rows and columns usually means either leaving many columns empty or splitting one logical record across a dozen linked tables just to describe it.

Amazon DocumentDB (with MongoDB compatibility) is AWS’s fully managed service for exactly this “notebook page” style of data, known as a document database. It stores records as flexible, JSON-like documents and speaks the same query language and drivers that the popular open-source database MongoDB uses, so applications already built against MongoDB can generally connect to DocumentDB with minimal changes, while AWS takes over the operational work of running the database reliably at scale.

It is worth spending a moment on why the word “flexible” keeps appearing throughout this topic, because it is easy to read past it without fully appreciating what it changes about day-to-day development work. In a relational table, adding a new field to every record typically requires an explicit schema change — a migration step that touches every existing row and must be carefully planned, especially on a large, actively used table. In a document collection, one document can simply start including a new field the moment the application starts writing it, while older documents that were created before that field existed remain perfectly valid without it. The application code decides how to handle a missing field, rather than the database forcing every record to carry every possible field from day one. This flexibility is enormously convenient during active development, when the exact shape of a record is still evolving, but it also shifts a certain amount of responsibility onto the application: since the database will not reject a document merely for having an unexpected shape, the application itself has to remain disciplined about which fields it actually relies on.

flowchart TB
    APP["Application"]
    LB["Cluster Endpoint"]
    subgraph Compute["Compute Layer"]
        PRI["Primary Instance (Writes)"]
        REP1["Replica Instance (Reads)"]
        REP2["Replica Instance (Reads)"]
    end
    subgraph Storage["Distributed Storage Volume"]
        AZ1[("Copy - AZ 1")]
        AZ2[("Copy - AZ 2")]
        AZ3[("Copy - AZ 3")]
    end

    APP --> LB
    LB --> PRI
    LB --> REP1
    LB --> REP2
    PRI --> Storage
    REP1 --> Storage
    REP2 --> Storage
    Storage --- AZ1
    Storage --- AZ2
    Storage --- AZ3
        

In the diagram, notice that every instance — the primary and every replica — connects to the same underlying storage volume rather than each keeping its own private copy of the data. This is fundamentally different from many traditional database setups, where each replica copies data from the primary over time and can lag behind. Because DocumentDB’s storage layer is shared, replicas read the exact same up-to-date data the primary writes, without needing to physically duplicate it themselves.

It is worth clarifying exactly what each instance in the compute layer is, and is not, responsible for, since this is a common source of confusion for anyone coming from a traditional single-server database background. An instance is responsible for parsing and executing queries, enforcing indexes, managing in-memory caching of frequently accessed data, and coordinating transactions. An instance is not responsible for physically holding the durable copy of the data on its own local disk the way a traditional database server would; that job belongs entirely to the shared storage volume. This is precisely why an instance can fail, be replaced, or be resized without any risk of data loss purely from that event — the instance itself was never the only place the data lived in the first place.

This division also explains why resizing a DocumentDB instance tends to be a relatively fast, low-drama operation compared to resizing storage on a traditional server. Growing storage on a traditional single-server database sometimes involves provisioning new physical disks and migrating data onto them, a process that can take hours or days depending on data volume. Because DocumentDB’s storage layer already grows automatically and independently of any specific instance, resizing an instance is really just swapping in a different amount of CPU and memory that connects to the exact same, unchanged storage volume underneath.

Understanding what actually happens during a write is the fastest way to understand why DocumentDB behaves the way it does.

This is a meaningfully different internal model from the classic “primary copies data to each replica one by one” approach used by many self-managed databases. Instead of the primary being personally responsible for pushing every byte of every change out to every replica, the heavy lifting of durability and distribution is delegated entirely to the storage layer itself, which was purpose-built for exactly that job. The practical result is that replicas tend to stay extremely close to current, and adding a new replica does not create the kind of heavy, disruptive copying process that traditional replication often requires.

It is worth pausing on why this shared-storage approach exists at all, rather than treating it as an arbitrary design choice. Traditional replication asks the primary to do two jobs simultaneously: answer the application’s queries, and separately push a copy of every change out to each replica over the network. As more replicas are added, that second job grows heavier, and at some point the primary spends a meaningful share of its effort just keeping replicas in sync rather than serving the application. DocumentDB’s shared storage volume removes that second job almost entirely. The primary only needs to write its changes to the storage layer once; every replica then reads from that same layer independently, on its own schedule, without the primary needing to personally deliver anything to them. Adding a tenth replica therefore costs the primary essentially nothing extra, which is a meaningfully different scaling curve than classic replica-chain architectures.

sequenceDiagram
    participant App as Application
    participant Pri as Primary Instance
    participant Store as Storage Volume (3 AZs)
    participant Rep as Replica Instance

    App->>Pri: Write request (insert/update)
    Pri->>Store: Persist change
    Store-->>Pri: Durability confirmed
    Pri-->>App: Write acknowledged
    App->>Rep: Read request
    Rep->>Store: Fetch current data
    Store-->>Rep: Return data
    Rep-->>App: Deliver result
        

Over the lifetime of a cluster, the storage volume grows automatically in the background as documents are added, up to very large sizes, without an administrator manually attaching new disks. Backups happen continuously in the background as well, capturing a rolling window of point-in-time restore capability, so recovering from an accidental bad write typically does not require restoring from last night’s full backup — a much narrower moment in time can usually be targeted instead.

DocumentDB separates two very different scaling questions, and it is worth answering them one at a time. The first question is “can I handle more reads?” This is solved by adding replica instances, each of which can independently serve read traffic from the same shared storage volume, up to fifteen replicas per cluster. The second question is “can I handle more writes, or bigger instances?” This is solved by resizing the primary instance to a larger compute class, since all writes ultimately pass through a single primary at any given moment.

A useful mental model is separating a workload into “read-heavy” and “write-heavy” categories before choosing an architecture. A product catalog viewed by millions of shoppers but updated by only a handful of staff is intensely read-heavy, and scales beautifully simply by adding replica instances behind the reader endpoint. A high-frequency logging system that constantly writes new records, by contrast, is write-heavy, and its ceiling is set primarily by how large a single primary instance can be sized, since writes cannot currently be spread across multiple primaries in one cluster.

It also helps to think about latency separately from raw throughput, since the two are easy to conflate. Throughput describes how many operations a cluster can absorb per second in aggregate; latency describes how long any single operation takes to complete from the application’s point of view. Adding replicas primarily improves aggregate read throughput by spreading load across more machines, but it does very little to change the latency of any single query, since each replica still has to actually read the same underlying storage volume. Improving latency for an individual slow query is much more often a matter of good indexing on the collection being queried, or choosing an instance class with more available memory so frequently accessed documents can be served from memory rather than requiring a slower storage read. Teams that skip this distinction sometimes add replica after replica trying to fix a “the app feels slow” complaint, when the actual root cause was an unindexed query pattern that no number of replicas could fix.

Durability in DocumentDB comes primarily from the storage layer, which automatically maintains six copies of the data spread across three separate Availability Zones. Losing an entire Availability Zone, or even up to two individual storage copies, still leaves the data safely intact and readable, because enough independent copies remain elsewhere.

It helps to separate durability of the data from availability of the service, the same way a bank vault’s contents being safe is a different guarantee from the bank’s front doors being open for business. DocumentDB’s storage design focuses heavily on the first guarantee — the data itself surviving hardware failures — while its automated failover mechanism focuses on the second guarantee — restoring the ability to actually read and write that data as quickly as possible after a compute-level failure. A well-designed cluster typically layers in multiple replicas specifically so that failover has somewhere fast to land, rather than needing to build an entirely new instance from scratch after a failure.

There is also a subtler form of resilience worth understanding: quorum-based writes. Rather than waiting for every single one of the six storage copies to confirm a write before telling the application it succeeded, DocumentDB’s storage layer only needs a majority of copies to acknowledge the write. This means a temporary slowdown or brief unavailability in one or even two individual storage copies does not stall every write across the entire cluster; the system can keep moving as long as a healthy majority is responding. This same majority-based thinking is what allows the storage layer to tolerate the loss of an entire Availability Zone without losing any acknowledged data, since the remaining zones alone still hold enough copies to form a majority.

These layers again answer different questions rather than duplicating one another. VPC isolation decides whether a connection attempt can even reach the cluster’s network address at all. TLS decides whether, once a connection is allowed, the actual conversation between application and database can be read by anyone listening along the way. Encryption at rest decides whether the physical storage media, if somehow accessed directly, reveals anything meaningful. And authentication decides, once someone has successfully connected over an allowed, encrypted path, precisely what they are permitted to do. A secure deployment intentionally uses all four, because leaving any single layer open effectively unlocks one of the four doors even though the other three remain shut.

One detail beginners often overlook is that encryption at rest, if desired, must generally be enabled when a cluster is first created; it cannot always be toggled on afterward without creating a new, encrypted cluster and migrating data into it. This makes it one of those decisions worth getting right during initial planning rather than treating as something to revisit casually later, especially for workloads that are known from the start to involve sensitive or regulated information.

Amazon CloudWatch automatically collects metrics such as CPU utilization, read and write throughput, storage consumed, and replication lag for every instance in a cluster, giving an operations team a continuous picture of cluster health without installing any separate monitoring agent.

Three of these metrics deserve particular attention because each catches a different kind of emerging problem. CPU utilization on the primary instance answers “is my current instance size still big enough for the write workload,” and a steadily climbing baseline over weeks is the classic early warning sign that a larger instance class should be scheduled before performance actually degrades for users. Replica lag answers “how current is the data my read replicas are serving,” which matters most for applications sensitive to reading slightly stale information right after a write. Storage used answers a purely financial and planning question, since storage grows automatically but customers naturally want visibility into that growth over time rather than being surprised by it.

Beyond the metrics themselves, DocumentDB also supports collecting detailed profiler-style logs of individual slow operations, which can be sent to CloudWatch Logs for deeper analysis. This is particularly valuable during application development, when a team wants to identify which specific query patterns are consuming disproportionate resources, rather than only seeing an aggregate CPU or throughput number without any insight into which particular operation caused it. Establishing this kind of logging early, before a performance problem actually appears in production, tends to save far more time later than trying to reconstruct what happened after the fact from aggregate metrics alone.