Navigation

Change Sharded Cluster to WiredTiger

Note

Starting in version 4.0, MongoDB deprecates the MMAPv1 storage engine and will remove MMAPv1 in a future release.

Use this tutorial to update MongoDB 4.0 sharded clusters to use WiredTiger.

For earlier versions of MongoDB:

Considerations

Downtime

If you change the host or port of any shard, you must update the shard configuration as well.

Default Bind to Localhost

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.

Config Servers

Starting in version 3.4, config servers must be deployed as replica sets (CSRS). As such, version 3.4+ config servers already use the WiredTiger storage engine.

XFS and WiredTiger

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

Procedure

For each replica set shard, to change the storage engine to WiredTiger:

A. Update the secondary members to WiredTiger.

Update the secondary members one at a time:

1

Shut down the secondary member.

In the mongo shell, shut down the secondary.

db.shutdownServer()
2

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

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

Start mongod with WiredTiger.

Start mongod, specifying wiredTiger as the --storageEngine and the prepared data directory for WiredTiger as the --dbpath. Specify additional options, such as --bind_ip, as appropriate for this replica set member.

Warning

Before you bind to other ip addresses, consider enabling access control and other security measures listed in Security Checklist to prevent unauthorized access.

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

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.

B. Step down the primary.

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

rs.stepDown()

C. Update the old primary.

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

1

Shut down the secondary member.

In the mongo shell, shut down the secondary.

db.shutdownServer()
2

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

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

Start mongod with WiredTiger.

Start mongod, specifying wiredTiger as the --storageEngine and the prepared data directory for WiredTiger as the --dbpath. Specify additional options, such as --bind_ip, as appropriate for this replica set member.

Warning

Before you bind to other ip addresses, consider enabling access control and other security measures listed in Security Checklist to prevent unauthorized access.

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

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 procedure for the other shards.