Replication

A replica set is a group of mongod instances that elect a single primary and replicate the primary's writes to secondaries. The replication subsystem under src/mongo/db/repl/ coordinates elections, applies the oplog, performs initial sync, and exposes the hello/replSetGetStatus topology surface.

Purpose

Replication provides:

• High availability — secondaries can be promoted if the primary becomes unavailable.
• Read scaling — reads with readPreference other than primary can target secondaries.
• Durability — writes can be acknowledged with various writeConcern settings ({w: "majority"}, {w: 1}, {j: true}, etc.) that gate on replication progress.
• Change feeds — the oplog is the source of truth for change streams and many cross-cluster tools.

Topology

graph TD
    P[Primary mongod]
    S1[Secondary mongod]
    S2[Secondary mongod]
    A[Arbiter]

    P -->|heartbeat| S1
    P -->|heartbeat| S2
    S1 -->|heartbeat| P
    S1 -->|heartbeat| S2
    S2 -->|heartbeat| P
    S2 -->|heartbeat| S1
    A -->|heartbeat / vote| P
    A -->|heartbeat / vote| S1
    A -->|heartbeat / vote| S2

    P -->|oplog stream| S1
    P -->|oplog stream| S2

Each member has a configuration in local.system.replset describing its hosts, priority, vote weight, and tags. Heartbeats propagate liveness and last-applied opTime; the TopologyCoordinator decides who's primary based on the data it sees.

The oplog

The oplog is local.oplog.rs, a capped collection that records every write. Each entry is a BSON document with:

• ts — Timestamp(secs, inc) — the cluster-monotonic timestamp.
• t — election term.
• op — operation type (i insert, u update, d delete, n no-op, c command).
• ns — namespace.
• o — payload.
• o2 — old image / query (for updates and deletes).
• wallTime, prevOpTime, txnNumber, stmtId, ui (collection UUID), and many others.

The format is documented in src/mongo/db/repl/oplog_entry.idl.

The oplog is appended on the primary by the OpObserver chain (src/mongo/db/op_observer/). Secondaries pull batches via a OplogFetcher, buffer them through the OplogBuffer, and apply via the OplogApplier.

Election

Elections use a Raft-inspired protocol (PV1):

• A primary issues regular heartbeats. If a majority of voters lose touch, candidates stand for election.
• Each candidate increments its term and requests votes; voters grant a vote if the candidate's lastApplied is at least as new as their own.
• A candidate that wins a quorum becomes primary, takes over write traffic, and stretches the cluster's currentTerm.

The state machine lives under src/mongo/db/repl/topology_coordinator* and src/mongo/db/repl/replication_coordinator_impl*. Formal models are in src/mongo/tla_plus/.

Initial sync

When a new node joins, it performs initial sync:

1. Picks a sync source.
2. Clones every database, collection-by-collection.
3. Builds indexes.
4. Applies the oplog produced during the clone phase to catch up.
5. Transitions to SECONDARY.

Initial sync code is under src/mongo/db/repl/initial_sync/. The state machine is intricate — many failure modes (sync source failover, index build failures, dropped collections during clone) are handled inline.

Steady-state apply

Once caught up, a secondary runs a steady-state apply loop:

graph LR
    Fetch[OplogFetcher] -->|batches| Buffer[OplogBuffer]
    Buffer --> Applier[OplogApplier]
    Applier -->|parallel writes| Writers[Writer threads]
    Writers --> Storage[WiredTiger]
    Applier -->|advance opTime| Coord[ReplicationCoordinator]

The applier batches oplog entries and dispatches them to a worker pool that respects the same conflict rules as the primary (per-document and per-collection ordering, multi-statement transaction grouping). Implementation is in src/mongo/db/repl/oplog_applier_impl.cpp and surrounding files.

Read and write concern

• writeConcern: {w: N} — the primary waits for N members to acknowledge before returning.
• writeConcern: {w: "majority"} — waits for a majority. Combined with the majority commit point, this gives durability across a primary failure.
• readConcern: "majority" — reads from a snapshot at the cluster's majority commit point, hiding concurrent un-replicated writes.
• readConcern: "snapshot" — used by transactions; reads from a single cluster-wide timestamp.
• readConcern: "linearizable" — performs a no-op write to confirm the primary is still primary.

The read/write concern defaults are tracked in src/mongo/db/read_write_concern_defaults.cpp and propagated cluster-wide through cluster parameters.

Primary-only services (POS)

Long-running primary-only work uses the primary-only service framework described in docs/primary_only_service.md. Each PrimaryOnlyService has:

• A persistent state document.
• A constructor invoked when the local node steps up to primary.
• A run() method that drives the service to completion.
• Automatic teardown on step-down.

Examples of POSes: the resharding coordinator, the DDL coordinator (sharded DDL), the tenant migration recipient, the internal transactions reaper.

dbcheck

dbcheck is an online consistency checker that walks collections and validates secondary copies match the primary. It runs as background work on each member, with results captured in local.system.healthlog. Source: src/mongo/db/repl/dbcheck/.

Key source files

File	Purpose
src/mongo/db/repl/oplog.cpp	Oplog append/read primitives.
src/mongo/db/repl/oplog_entry.idl	Oplog entry schema.
src/mongo/db/repl/replication_coordinator_impl.cpp	The replication coordinator state machine.
src/mongo/db/repl/topology_coordinator.cpp	Election and topology decisions.
src/mongo/db/repl/oplog_applier_impl.cpp	Secondary apply loop.
src/mongo/db/repl/initial_sync/	Initial sync state machine.
src/mongo/db/repl/primary_only_service.cpp	POS framework.
src/mongo/db/repl/hello/	The hello/isMaster topology endpoint.
src/mongo/db/repl/dbcheck/	Online consistency check.

Integration points

• The op observer writes oplog entries on every CRUD operation.
• The storage engine provides timestamps and snapshots that the replication system uses for read concern.
• The transport layer ships oplog batches between members.
• The change streams subsystem and most cross-cluster tooling consume the oplog.
• The shard role uses the replication coordinator to gate writes during step-down and replication state transitions.

Entry points for modification

Most changes to oplog entry schema land in oplog_entry.idl plus the corresponding append helper in op_observer_impl.cpp. New replica-set commands go in src/mongo/db/repl/repl_commands.cpp. Election-protocol changes touch topology_coordinator.cpp and the corresponding TLA+ models in src/mongo/tla_plus/. Initial-sync changes are concentrated in src/mongo/db/repl/initial_sync/. The unit tests in src/mongo/db/repl/*_test.cpp and the replica_sets resmoke suite are the primary safety nets.