Operate a store

Back up a directory or OPFS namespace before activating history or importing into it.

Every store carries format marker 5 and a random store identity. Opening a store with any other marker fails with SCHEMA_MISMATCH, so a store written by another build is never misread: export it with the build that wrote it and import the archive. Copying a closed physical store preserves its identity and cursor scope.

Start recording

Call db.ensureCollection(name, { $trackHistory: true }). Enabling a collection that already holds documents seeds them at one effective instant. Reads before that baseline raise HISTORY_UNAVAILABLE. A newly created tracked collection can accept backdated initial facts.

For large collections, set historyBatchSize and resume an interrupted baseline by repeating the same call. Ordinary reads remain available during activation. The collection accepts writes after the baseline publishes.

Reclaim space

Every commit appends copy-on-write pages and never overwrites old ones, so a store grows faster than its data. VERIFIED: in docs/benchmarks/mongodb-node.json, compaction[].reclaimedBytes shows what background compaction removed while loading each collection. A connection compacts in the background:

The live size is the size the last compaction left, scaled by the stored entries since, so inserted documents do not count as garbage and deleted ones do. VERIFIED: a 100,000-document load into an empty directory store copied it once during the load and once after it.

db.stats().autoCompaction reports the state and counts runs, conflicts, failures and reclaimed bytes. A failed copy, for example on a full disk, waits for another growth step instead of retrying at once. For a one-off bulk import, open with autoCompact: false, load, then call compact() and collect() once, to choose when that copy runs. Snapshots pin their generation, so close them when finished.

Size the page cache

The database caches decoded tree pages up to maxCacheBytes (64 MiB of encoded pages) and maxCachePages (16,384); with compact pages the page count binds first, at about 2 KiB of heap per page. Document values are never cached; scans read and decode them every time. db.stats().cacheBytes and cachePages show the current use. When they sit at the limit and scans or reads by ID slow down as a collection grows, raise both options when opening the database.

Scan in worker threads

On directory storage, scans that cover 5,000 rows or more run in a pool of up to four worker threads, one fewer than the CPUs: full-collection aggregates, projections and search index builds, and exports. Short pages stay in the calling thread. Set storage: { scanWorkers: 0 } in openDirectory() to turn the pool off, for example when the process already runs one database per CPU. Memory and browser stores scan in the calling thread. On network or slow storage set storage: { syncReadBytes: 0 }, so a slow read does not block the event loop.

Answer aggregates in worker threads

A directory store answers an aggregate or count in query worker threads when it scans the whole collection, the collection holds at least minRows (1,000) documents, and DataView can merge its parts: counts, minima, maxima and BigInt sums always, sum and avg only under numberMode: 'exact'. It runs up to eight workers, one fewer than the CPUs, each with its own handle of the store. The first such query starts them and runs in the calling thread, as does every query while they start; they close after 30 seconds without a query. Each running worker holds a page cache of up to 64 MiB. db.stats().parallel shows the state, the queries the workers answered, fallbacks (queries sent back to the calling thread after a worker failed) and the last start error. Set parallel: false in openDirectory() to turn them off, or parallel: { workers, minRows } to size them.

Move data

Use exportStream({ history: 'full' }) and import into an empty target to carry effective intervals, tombstones, schema changes and source receipts. A latest-only archive carries current documents and index definitions. A logical restore has its own physical store identity. Document history · Archive format and limits