Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Change Replica Set to WiredTiger

Note

Starting in version 4.2, MongoDB removes the deprecated MMAPv1 storage engine. If upgrading to MongoDB 4.2 from a MongoDB 4.0 deployment 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 a rolling fashion to avoid downtime.

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

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

The procedure below disables "majority" read concern for MongoDB 4.0.3 PSA architecture by including --enableMajorityReadConcern false. If you are running a MongoDB 4.0.1 or 4.0.2 PSA architecture, first upgrade to the latest 4.0 version in order to disable this read concern.

Note

Disabling "majority" read concern disables support for Change Streams for MongoDB 4.0 and earlier. For MongoDB 4.2+, disabling read concern "majority" has no effect on change streams availability.

For more information on PSA architecture and read concern "majority", see .

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

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

With the WiredTiger storage engine, using XFS for data bearing nodes is recommended on Linux. For more information, see Kernel and File Systems.

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

MMAPv1 Restrictions
Short Description
Number of Namespaces
For MMAPv1, the number of namespaces is limited to the size of the namespace file divided by 628.
Size of Namespace File
For MMAPv1, namespace files can be no larger than 2047 megabytes.
Database Size
The MMAPv1 storage engine limits each database to no more than 16000 data files.
Data Size
For MMAPv1, a single mongod instance cannot manage a data set that exceeds maximum virtual memory address space provided by the underlying operating system.
Number of Collections in a Database
For the MMAPv1 storage engine, the maximum number of collections in a database is a function of the size of the namespace file and the number of indexes of collections in the database.

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

To update a member to WiredTiger, the procedure removes a member's data, starts mongod with WiredTiger, and performs an initial sync.

Update the secondary members one at a time:

1

In mongosh, shut down the secondary.

use admin
db.shutdownServer()
2

Prepare a data directory for the new mongod instance that will run with the WiredTiger storage engine. mongod must have read and write permissions for this directory. You can either delete the contents of the stopped secondary member's current data directory or create a new directory entirely.

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

3

Remove any MMAPv1 Specific Configuration Options from the mongod instance configuration.

4

Start mongod, specifying wiredTiger as the --storageEngine and the prepared data directory for WiredTiger 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 unauthorized access. For a complete list of security recommendations, see Security Checklist. At minimum, consider enabling authentication and hardening network infrastructure.

Since no data exists in the --dbpath, the mongod will perform an initial sync. The length of the initial sync process depends on the size of the database and network connection between members of the replica set.

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

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

Important

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

Once all the secondary members have been upgraded to WiredTiger, connect mongosh to the primary and use rs.stepDown() to step down the primary and force an election of a new primary.

rs.stepDown()

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

1

In mongosh, shut down the secondary.

use admin
db.shutdownServer()
2

Prepare a data directory for the new mongod instance that will run with the WiredTiger storage engine. mongod must have read and write permissions for this directory. You can either delete the contents of the stopped secondary member's current data directory or create a new directory entirely.

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

3

Remove any MMAPv1 Specific Configuration Options from the mongod instance configuration.

4

Start mongod, specifying wiredTiger as the --storageEngine and the prepared data directory for WiredTiger 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 unauthorized access. For a complete list of security recommendations, see Security Checklist. At minimum, consider enabling authentication and hardening network infrastructure.

Since no data exists in the --dbpath, the mongod will perform an initial sync. The length of the initial sync process depends on the size of the database and network connection between members of the replica set.

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

←  Change Standalone to WiredTigerChange Sharded Cluster to WiredTiger →