Skip to content

Databases Updated 2026-05-29

MongoDB high availability

High-availability options for MongoDB on Stack Harbor PaaS — auto-clustering with replica sets, manual replica-set configuration, and failover behaviour.

MongoDB’s HA story is the replica set — a group of MongoDB nodes with one primary and one or more secondaries, replicating asynchronously, with automated primary election when the primary fails. Stack Harbor PaaS provisions replica sets from the topology wizard, and supports manual configuration when you want full control.

Auto-clustering

The simplest path is the topology wizard:

  1. Click New Environment in the dashboard.
  2. Pick MongoDB in the database row.
  3. Enable Auto-Clustering.
  4. Pick the number of replica-set members (3 is the conventional minimum for HA).
  5. Set the cloudlet limit per node and the environment name.
  6. Click Create.

The platform provisions the members, configures them as a replica set with a generated name (e.g. rs0), and emails the initial credentials.

Manual replica-set setup

When you want full control over the replica-set configuration — custom replica-set name, custom member priorities, custom write concern settings — set it up by hand.

1. Provision the nodes

Create a MongoDB environment with the number of nodes you want as replica-set members, without auto-clustering. Each node starts as a standalone MongoDB instance.

2. Configure mongod for replication

On each node, edit /etc/mongod.conf and add (or set) the replication block:

replication:
  replSetName: rs0

Restart mongod on each node after the edit. The nodes are now ready to participate in a replica set named rs0, but no member is part of one yet.

3. Initiate the replica set

Open the Web SSH console on the node you want as the initial primary, and connect with mongosh:

mongosh --host node{node_id}-{environment_name}.{domain} -u root -p

Then initiate the replica set:

rs.initiate({
  _id: 'rs0',
  members: [
    { _id: 0, host: 'node{a}-{env}.{domain}:27017' },
    { _id: 1, host: 'node{b}-{env}.{domain}:27017' },
    { _id: 2, host: 'node{c}-{env}.{domain}:27017' },
  ],
});

Check the status:

rs.status();

You should see one node marked as PRIMARY and the rest as SECONDARY.

4. Configure write concern

For an HA-significant write workload, set the default write concern to majority. From mongosh on the primary:

db.adminCommand({
  setDefaultRWConcern: 1,
  defaultWriteConcern: { w: 'majority', wtimeout: 5000 },
});

This blocks each write until a majority of replica-set members has acknowledged. It costs a bit of latency in exchange for the guarantee that a committed write survives a primary failover.

Failover behaviour

When the primary fails, the remaining replica-set members elect a new primary. The election takes a few seconds; during that window, writes from the application fail with a NotMasterError (or NotWritablePrimary in newer drivers).

Modern MongoDB drivers handle this transparently — the driver retries writes against the new primary once election completes. The application sees a brief latency spike rather than an outage. Use the retryable writes option (retryWrites=true in the connection string, the default in current drivers) to make this automatic.

Read preference

By default, the driver routes all reads to the primary. To balance read load across secondaries, set the read preference on the connection or per query:

  • primary — reads from the primary only (default).
  • primaryPreferred — reads from the primary if available, otherwise from a secondary.
  • secondary — reads from a secondary only. Fails if no secondary is available.
  • secondaryPreferred — reads from a secondary if available, otherwise from the primary.
  • nearest — reads from the member with the lowest network latency, primary or secondary.

Secondary reads are not strongly consistent — a secondary may lag the primary by some amount of time. Avoid secondary reads for read-after-write workflows where the application reads a value it just wrote.

See also