Skip to content
Tutorials Center
My learning

Topics

Lesson 53 of 70 ยท Replication, sharding and operations

Storage Engine Internals: WiredTiger, Journaling and Checkpoints

Understand MongoDB's WiredTiger storage engine: document-level concurrency, the cache and its sizing, compression, the journal, checkpoints and how a crash is recovered.

When you run insertOne, the document seems to go "into the database". Underneath, a component called the storage engine decides how it is stored in memory, written to disk, compressed, protected against a power failure and read back. In MongoDB that engine is WiredTiger, the default since MongoDB 3.2. You can use MongoDB for years without thinking about it, but understanding the basics explains the behavior of memory use, disk space, w/j write concerns and crash recovery, and it makes you better at sizing servers and reading serverStatus output.

The commands here are real mongosh and mongod.conf syntax and cannot run on this page. The TryIts are plain JavaScript models of two ideas (a journal with checkpoints for crash recovery, and cache and compression arithmetic) so you can experiment with them. They are simplified teaching models, not WiredTiger.

Where the storage engine sits

MongoDB is layered. The part you talk to (mongod) parses commands, plans queries, enforces security and handles replication. It then delegates the actual reading and writing of data to a pluggable storage engine through a defined interface.

flowchart TB
  A["Your application and driver"] --> B["mongod: query language, planner, security, replication"]
  B --> C["Storage engine API"]
  C --> D["WiredTiger: cache, B-trees, compression, journal"]
  D --> E[("Data files and journal on disk")]

The server decides what to do; the storage engine decides how the bytes are kept.

WiredTiger is the engine used by default and by Atlas. MongoDB Enterprise also offers an in-memory engine for special cases. For everything else, assume WiredTiger.

What WiredTiger gives you

  • Document-level concurrency. Writers lock only the documents they change, using multi-version concurrency control (MVCC), so many clients can read and write the same collection at once. Readers see a consistent snapshot and do not block writers. This is a big reason MongoDB scales well on multi-core machines.
  • B-tree storage for collections and indexes. Each collection and each index is a separate file (collection-*.wt and index-*.wt in the data directory).
  • Compression of both data and indexes (below).
  • Checkpoints and a journal for durability (below).

The cache

WiredTiger keeps recently used data in its own internal cache, in uncompressed form, so reads and writes of hot data are memory operations. By default the cache size is the larger of 50% of (RAM minus 1 GB) and 256 MB. On a 16 GB server that is 7.5 GB. You can change it:

YAML
# mongod.conf
storage:
  wiredTiger:
    engineConfig:
      cacheSizeGB: 6

The rest of RAM is not wasted: the operating system's file system cache holds the compressed pages that WiredTiger reads from disk, and mongod needs memory for connections, sorts and aggregations. That is why you should not set cacheSizeGB close to total RAM, and why running two mongod processes on one host, or a container with a tight memory limit, needs an explicit smaller cache.

When the cache fills, WiredTiger evicts the least recently used pages (writing dirty pages to disk first). If the working set (the data and indexes your queries touch most) does not fit, queries start reading from disk and latency rises. You can watch the cache in serverStatus:

JavaScript
const c = db.serverStatus().wiredTiger.cache
c["maximum bytes configured"]       // the configured cache size
c["bytes currently in the cache"]   // how full it is
c["tracked dirty bytes in the cache"] // changed pages not yet checkpointed
c["pages read into cache"]          // growing fast = the working set does not fit

Warning signs are a cache that is always near full with a rapidly increasing "pages read into cache", and queries that slow down when the data set grows. Fixes are better indexes (see How Indexes Work), a smaller working set, or more RAM.

Compression

WiredTiger compresses each collection's blocks on disk with snappy by default, which is fast and modest (often 2x to 4x smaller than the raw BSON for typical JSON-like data). Alternatives are zstd (better ratio, a little more CPU, available since 4.2) and zlib (high ratio, slower), or none. Indexes use prefix compression (repeated key prefixes are stored once) by default.

JavaScript
db.createCollection("events", {
  storageEngine: { wiredTiger: { configString: "block_compressor=zstd" } }
})

Compression lowers disk use and I/O at the cost of CPU. For write-heavy hot data keep snappy; for large, rarely read data (logs, archives) zstd is often worth it. You can compare db.collection.stats() values size (uncompressed) and storageSize (on disk) to see the ratio you actually get. Data in the cache is uncompressed, so compression saves disk, not RAM.

The journal: surviving a crash between checkpoints

Writing every change to its final place in the B-tree files immediately would be slow. WiredTiger instead uses two mechanisms together:

  1. Checkpoints. About every 60 seconds, WiredTiger writes a consistent snapshot of all data to disk. A checkpoint is a complete, valid state of the files; the previous one stays valid until the new one is finished.
  2. The journal (write-ahead log). Each change is also appended to a journal file, a sequential log that is cheap to write. The journal is flushed to disk about every 100 ms (storage.journal.commitIntervalMs), or at once for a write that asks for it.

If the server crashes, recovery is simple: start from the last checkpoint (a consistent state), then replay the journal records written after it. Everything that reached the journal is recovered. Only the last fraction of a second of changes, those not yet flushed to the journal, can be lost.

You decide how strict a single write is with the write concern, covered in Read and Write Concerns:

JavaScript
db.orders.insertOne({ item: "lamp" }, { writeConcern: { w: 1, j: true } })

j: true makes the server acknowledge only after the write is in the on-disk journal. With a replica set and w: "majority", the write is also journaled and replicated on enough members, so it survives the loss of a single machine. Without j, an acknowledged write can be lost in a crash if it was not yet flushed (the replica set protects against that with copies elsewhere).

The first TryIt models this: writes go into memory and the journal, a checkpoint saves a snapshot, and a crash wipes memory. Recovery loads the checkpoint and replays whatever the journal had received.

JS Checkpoint plus journal: surviving a crash

Press Run (or Ctrl + Enter) to see the console output here.

No output.

a and b come back from the checkpoint, c from the journal replay, and d is gone because nothing had made it to disk. The second engine used j: true on every write, so nothing acknowledged was lost.

Putting numbers on it

Sizing questions come up all the time: how big will the data be on disk? How much cache do I get? The second TryIt computes both from a few inputs. The compression ratios are typical illustrations, not guarantees; measure your own data with collection.stats().

JS Cache size and on-disk size estimator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The cache holds uncompressed pages, so even a collection that compresses to 30 GB on disk needs its hot part to fit in cache uncompressed. That is why the working set size, not the file size, drives memory planning.

Practical consequences

  • Disk space is not freed on delete. Deleting documents leaves free space inside the files that WiredTiger reuses; the files shrink only when you compact or rebuild the collection. Check storageSize against size to see reusable space.
  • Take backups that respect the journal. A file copy of a running mongod is safe only if it is a filesystem snapshot of the data and journal together, or if you use mongodump/Atlas backups (see Backup and Restore).
  • Put the journal on reliable disk. Fast SSDs make j: true writes cheap; slow disks make them the bottleneck.
  • Do not disable the journal on production servers: it is part of the crash recovery guarantee. Run a replica set for availability and copies on other machines (see Replication).
  • Watch the cache metrics when you add indexes: each index competes for the same cache. A compound index that avoids a scan can save more memory than it costs.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the default storage engine in modern MongoDB?

    WiredTiger has been the default since MongoDB 3.2. MMAPv1 was removed in 4.2.
  2. 2. How does WiredTiger recover after a crash?

    A checkpoint is a consistent snapshot; the journal holds the changes since then.
  3. 3. What does the write concern j: true guarantee?

    With j: true the acknowledgment waits for the journal flush, so the write survives a crash of that server.
  4. 4. By default, how large is the WiredTiger cache?

    The default leaves room for the operating system file cache and other work.
  5. 5. Does compression reduce the memory used by the WiredTiger cache?

    Pages are decompressed when read into the cache, so plan memory for the uncompressed working set.

Summary

  • WiredTiger is MongoDB's default storage engine, with document-level concurrency (MVCC), B-tree files, compression, a cache, checkpoints and a journal.
  • The cache defaults to the larger of 50% of (RAM minus 1 GB) and 256 MB, holds uncompressed pages, and the rest of RAM serves the OS file cache.
  • Data is compressed on disk (snappy by default; zstd and zlib are options) and indexes use prefix compression.
  • A checkpoint about every 60 seconds plus a journal flushed about every 100 ms let the server recover after a crash; j: true waits for the journal.
  • Deleted space is reused inside the files, not returned to the operating system; measure size against storageSize and watch cache statistics.

Next, put these ideas to work in Backup and Restore.