Change Replica Set to WiredTiger

Note

Starting in version 4.2, MongoDB removes the deprecated MMAPv1storage engine. If upgrading to MongoDB 4.2 from a MongoDB 4.0deployment that uses MMAPv1, you must upgrade to WiredTiger.

Use this tutorial to update a replica set to use WiredTiger. The procedure updates the replica set in arolling fashion to avoid downtime.

Considerations

Replica sets can have members with different storage engines. As such,you can update members to use the WiredTiger storage engine in arolling fashion.

PSA 3-member Architecture

Starting in MongoDB 3.6, "majority" read concern,available for WiredTiger, is enabled by default. However, for MongoDB4.0.3+, if you have a three-member replica set with aprimary-secondary-arbiter (PSA) architecture, you can disable"majority" read concern. Disabling"majority" for a three member PSA architecture avoidspossible cache-pressure build up.

The procedure below disables "majority" read concern forMongoDB 4.0.3 PSA architecture by including—enableMajorityReadConcern false. If you are running a MongoDB 4.0.1 or4.0.2 PSA architecture, first upgrade to the latest 4.0 version inorder to disable this read concern.

Note

Disabling "majority" read concern disables supportfor Change Streams for MongoDB 4.0 and earlier. For MongoDB4.2+, disabling read concern "majority" has no effect on changestreams availability.

For more information on PSA architecture and read concern"majority", see Disable Read Concern Majority.

MongoDB 3.0 or Greater

You must be using MongoDB version 3.0 or greater in order to use theWiredTiger storage engine. If using an earlier MongoDB version, youmust upgrade your MongoDB version before proceeding to change yourstorage engine. To upgrade your MongoDB version, refer to theappropriate version of the manual.

Default Bind to Localhost

Starting with MongoDB 3.6, MongoDB binaries, mongod andmongos, bind to localhost by default.From MongoDB versions 2.6 to 3.4, only the binaries from theofficial MongoDB RPM (Red Hat, CentOS, Fedora Linux, and derivatives)and DEB (Debian, Ubuntu, and derivatives) packages would bind tolocalhost by default. To learn more about this change, seeLocalhost Binding Compatibility Changes.

XFS and WiredTiger

With the WiredTiger storage engine, using XFS for data bearing nodes isrecommended on Linux. For more information, seeKernel and File Systems.

MMAPv1 Only Restrictions

Once upgraded to WiredTiger, your WiredTiger deployment is notsubject to the following MMAPv1-only restrictions:

Procedure

The following procedure updates the replica set in a rolling fashion.The procedure updates the secondary members first, then stepsdown the primary, and updates the stepped-down member.

To update a member to WiredTiger, the procedure removes a member’sdata, starts mongod with WiredTiger, and performs aninitial sync.

A. Update the secondary members to WiredTiger.

Update the secondary members one at a time:

Shut down the secondary member.

In the mongo shell, shut down the secondary.

use admin
db.shutdownServer()

Prepare a data directory for the new mongod running with WiredTiger.

Prepare a data directory for the new mongod instance thatwill run with the WiredTiger storage engine. mongod must have readand write permissions for this directory. You can either delete thecontents of the stopped secondary member’s current data directory orcreate a new directory entirely.

mongod with WiredTiger will not start with data files created witha different storage engine.

Update configuration for WiredTiger.

Remove any MMAPv1 Specific Configuration Options from the mongodinstance configuration.

Start mongod with WiredTiger.

Start mongod, specifying wiredTiger as the—storageEngine and the prepared data directory forWiredTiger as the —dbpath.

Specify additional options as appropriate, such as—bind_ip.

Warning

Before binding to a non-localhost (e.g. publicly accessible)IP address, ensure you have secured your cluster from unauthorizedaccess. For a complete list of security recommendations, seeSecurity Checklist. At minimum, considerenabling authentication andhardening network infrastructure.

• General Use (For Most Architectures)
• PSA Architecture

mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --replSet <replSetName> --bind_ip localhost,<hostname(s)|ip address(es)>

Important

If you are running a three-member PSA architecture andMongoDB version 4.0.3+, include—enableMajorityReadConcern false to disable read concern majority. See PSA 3-member Architecture.

mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --replSet <replSetName> --bind_ip localhost,<hostname(s)|ip address(es)> --enableMajorityReadConcern false

Since no data exists in the —dbpath, the mongod will perform aninitial sync. The length of theinitial sync process depends on the size of the database and networkconnection between members of the replica set.

You can also specify the options in a configuration file. To specify the storage engine, usethe storage.engine setting.

Repeat the steps for the remaining secondary members, updating them oneat a time.

B. Step down the primary.

Important

If updating all members of the replica set to use WiredTiger, ensurethat all secondary members have been updated first before updatingthe primary.

Once all the secondary members have been upgraded to WiredTiger,connect a mongo shell to the primary and users.stepDown() to step down the primary and force an electionof a new primary.

rs.stepDown()

C. Update the stepped down primary.

When the primary has stepped down and become a secondary, update thesecondary to use WiredTiger as before:

Shut down the secondary member.

In the mongo shell, shut down the secondary.

use admin
db.shutdownServer()

Prepare a data directory for the new mongod running with WiredTiger.

Prepare a data directory for the new mongod instance thatwill run with the WiredTiger storage engine. mongod must have readand write permissions for this directory. You can either delete thecontents of the stopped secondary member’s current data directory orcreate a new directory entirely.

mongod with WiredTiger will not start with data files created witha different storage engine.

Update configuration for WiredTiger.

Remove any MMAPv1 Specific Configuration Options from the mongodinstance configuration.

Start mongod with WiredTiger.

Start mongod, specifying wiredTiger as the—storageEngine and the prepared data directory forWiredTiger as the —dbpath.

Specify additional options as appropriate, such as—bind_ip.

Warning

Before binding to a non-localhost (e.g. publicly accessible)IP address, ensure you have secured your cluster from unauthorizedaccess. For a complete list of security recommendations, seeSecurity Checklist. At minimum, considerenabling authentication andhardening network infrastructure.

• General Use (For Most Architectures)
• PSA Architecture

mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --replSet <replSetName> --bind_ip localhost,<hostname(s)|ip address(es)>

Important

If you are running a three-member PSA architecture andMongoDB version 4.0.3+, include—enableMajorityReadConcern false to disable read concern majority. See PSA 3-member Architecture.

mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --replSet <replSetName> --bind_ip localhost,<hostname(s)|ip address(es)> --enableMajorityReadConcern false

Since no data exists in the —dbpath, the mongod will perform aninitial sync. The length of theinitial sync process depends on the size of the database and networkconnection between members of the replica set.

You can also specify the options in a configuration file. To specify the storage engine, usethe storage.engine setting.