Skip to content

This documentation is for the end of life version of Percona Server for MongoDB and is no longer supported. You may want to see the current documentation.

Switching Storage Engines

By default, Percona Server for MongoDB runs with WiredTiger. There is also the original MMAPv1 storage engine, as well as optional Percona Memory Engine and MongoRocks storage engines to choose from. Each one is designed for specific purposes and workloads.

You can select a storage engine using the --storageEngine command-line option when you start mongod. Alternatively, you can set the storage.engine variable in the configuration file (by default, /etc/mongod.conf).

Data created by one storage engine is not compatible with other storage engines, because each one has its own data model. When changing the storage engine, you have to do one of the following:

See also

MongoDB Documentation: Configuration File Options

Data files created by one storage engine are not compatible with other storage engines, because each one has its own data model.

When changing the storage engine, the mongod node requires an empty dbPath data directory when it is restarted even when using Percona Memory Engine. Though in-memory storage engine stores all data in memory, some metadata files, diagnostics logs and statistics metrics are still written to disk.

Creating a new dbPath data directory for a different storage engine is the simplest solution. Yet when you switch between disk-using storage engines (e.g. from WiredTiger to Percona Memory Engine), you may have to delete the old data if there is not enough disk space for both. Double-check that your backups are solid and/or the replica set nodes are healthy before you switch to the new storage engine.

If there is data that you want to migrate and make compatible with the new storage engine, use the following methods:

  • for replica sets, use the “rolling restart” process.

    Switch to the new storage engine on the secondary node. Clean out the dbPath data directory (by default , /var/lib/mongodb) and edit the configuration file:

    $ service mongod stop
    $ rm -rf <dbpathDataDir>
    $ # Update the configuration file by setting the new
    $ # value for the storage.engine variable
    $ # set the engine-specific settings such as
    $ # storage.inMemory.engineConfig.inMemorySizeGB
    $ service mongod start
    

    Wait for the node to rejoin with the other replica set members and report the SECONDARY status.

    Repeat the procedure on the remaining nodes.

  • for a standalone instance or a single-node replica set, use the mongodump and mongorestore utilities:

    $ mongodump --out <dumpDir>
    $ rm -rf <dbpathDataDir>
    $ # Update the configuration file by setting the new
    $ # value for the storage.engine variable
    $ # set the engine-specific settings such as
    $ # storage.wiredTiger.engineConfig.cacheSizeGB or
    $ # storage.inMemory.engineConfig.inMemorySizeGB
    $ service mongod start
    $ mongorestore <dumpDir>
    

Data at Rest Encryption

Using Data at Rest Encryption means using the same storage.* configuration options as for WiredTiger. To change from normal to Data at Rest Encryption mode or backward, you must clean up the dbPath data directory, just as if you change the storage engine. This is because mongod cannot convert the data files to an encrypted format ‘in place’. It must get the document data again either via the initial sync from another replica set member or from imported backup dump.