- Release Notes >
- Release Notes for MongoDB 3.0 >
- Upgrade MongoDB to 3.0
Upgrade MongoDB to 3.0¶
On this page
In the general case, the upgrade from MongoDB 2.6 to 3.0 is a
binary-compatible “drop-in” upgrade: shut down the mongod
instances and replace them with mongod
instances running
3.0. However, before you attempt any upgrade please familiarize
yourself with the content of this document, particularly the procedure
for upgrading sharded clusters.
If you need guidance on upgrading to 3.0, MongoDB offers consulting to help ensure a smooth transition without interruption to your MongoDB application.
Upgrade Recommendations and Checklists¶
When upgrading, consider the following:
Upgrade Requirements¶
To upgrade an existing MongoDB deployment to 3.0, you must be running 2.6. If you’re running a version of MongoDB before 2.6, you must upgrade to 2.6 before upgrading to 3.0. See Upgrade MongoDB to 2.6 for the procedure to upgrade from 2.4 to 2.6. Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4.
If your existing MongoDB deployment is already running with
authentication and authorization, your user data model authSchema
must be at least version 3. To verify the version of your existing
authSchema
, see MongoDB 2.4 User Model Removed. To upgrade your
authSchema
version, see
Upgrade User Authorization Data to 2.6 Format for details.
Preparedness¶
Before upgrading MongoDB, always test your application in a staging environment before deploying the upgrade to your production environment.
Some changes in MongoDB 3.0 require manual checks and intervention. Before beginning your upgrade, see the Compatibility Changes in MongoDB 3.0 document to ensure that your applications and deployments are compatible with MongoDB 3.0. Resolve the incompatibilities in your deployment before starting the upgrade.
Downgrade Limitations¶
Once upgraded to MongoDB 3.0, you cannot downgrade to a version lower than 2.6.8.
If you upgrade to 3.0 and have run authSchemaUpgrade
, you
cannot downgrade to 2.6 without disabling --auth
or
restoring a pre-upgrade backup, as authSchemaUpgrade
discards the MONGODB-CR
credentials used in 2.6. See
Upgrade Existing MONGODB-CR Users to Use SCRAM-SHA-1.
Upgrade MongoDB Processes¶
Upgrade Standalone mongod
Instance to MongoDB 3.0¶
The following steps outline the procedure to upgrade a standalone
mongod
from version 2.6 to 3.0. To upgrade from version
2.4 to 3.0, upgrade to version 2.6
first, and then use the following procedure to upgrade from 2.6 to 3.0.
Upgrade Binaries¶
If you installed MongoDB from the MongoDB apt
, yum
, or zypper
repositories, you should upgrade to 3.0 using your package manager. Follow the
appropriate installation instructions
for your Linux system. This will involve adding a repository for the new
release, then performing the actual upgrade.
Otherwise, you can manually upgrade MongoDB:
Download 3.0 binaries.¶
Download binaries of the latest release in the 3.0 series from the MongoDB Download Page. See Install MongoDB for more information.
Change Storage Engine to WiredTiger¶
To change storage engine to WiredTiger, you will need to manually
export and upload the data using mongodump
and
mongorestore
.
Restart the mongod
with WiredTiger.¶
Restart the 3.0 mongod
, specifying wiredTiger
as the
--storageEngine
and the newly created data directory for
WiredTiger as the --dbpath
. Specify additional options as
appropriate.
You can also specify the options in a configuration file. To specify the storage engine, use
the new storage.engine
setting.
Upload the exported data using mongorestore
.¶
Specify additional options as appropriate. See
mongorestore
for available options.
Upgrade a Replica Set to 3.0¶
Prerequisites¶
- If the oplog contains entries generated by versions of MongoDB that precede version 2.2.1, you must wait for the entries to be overwritten by later versions before you can upgrade to MongoDB 3.0. For more information, see Replica Set Oplog Format Change
- Stricter validation in MongoDB 3.0 of replica set configuration may invalidate previously-valid replica set configuration, preventing replica sets from starting in MongoDB 3.0. For more information, see Replica Set Configuration Validation.
- All replica set members must be running version 2.6 before you can upgrade them to version 3.0. To upgrade a replica set from an earlier MongoDB version, upgrade all members of the replica set to version 2.6 first, and then follow the procedure to upgrade from MongoDB 2.6 to 3.0.
Upgrade Binaries¶
You can upgrade from MongoDB 2.6 to 3.0 using a “rolling” upgrade to minimize downtime by upgrading the members individually while the other members are available:
Upgrade secondary members of the replica set.¶
Upgrade the secondary members of the set one at a time by
shutting down the mongod
and replacing the 2.6 binary
with the 3.0 binary. After upgrading a mongod
instance,
wait for the member to recover to SECONDARY
state
before upgrading the next instance.
To check the member’s state, issue rs.status()
in the
mongo
shell.
Step down the replica set primary.¶
Use rs.stepDown()
in the mongo
shell to
step down the primary and force the set to failover. rs.stepDown()
expedites the failover procedure and is preferable to shutting down
the primary directly.
Upgrade the primary.¶
When rs.status()
shows that the primary has stepped down
and another member has assumed PRIMARY
state, shut down the
previous primary and replace the mongod
binary with the
3.0 binary and start the new instance.
Replica set failover is not instant and will render the set unavailable to accept writes until the failover process completes. This may take 30 seconds or more: schedule the upgrade procedure during a scheduled maintenance window.
Change Replica Set Storage Engine to WiredTiger¶
In MongoDB 3.0, replica sets can have members with different storage engines. As such, you can update members to use the WiredTiger storage engine in a rolling manner. Before changing all the members to use WiredTiger, you may prefer to run with mixed storage engines for some period. However, performance can vary according to workload.
Note
Before enabling the new WiredTiger storage engine, ensure that all replica set/sharded cluster members are running at least MongoDB version 2.6.8, and preferably version 3.0.0 or newer.
To change the storage engine to WiredTiger for an existing secondary replica set member, remove the member’s data and perform an initial sync:
Prepare data directory for WiredTiger.¶
mongod
with WiredTiger will not start if the
--dbpath
directory contains data files created with a
different storage engine.
For the stopped secondary member, either delete the content of the
data directory or create a new data directory. If creating a new
directory, ensure that the user account running mongod
has
read and write permissions for the new directory.
Restart the secondary member with WiredTiger.¶
Restart the 3.0 mongod
, specifying wiredTiger
as the
--storageEngine
and the data directory for WiredTiger as
the --dbpath
. Specify additional options as appropriate for
the member.
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 new storage.engine
setting.
To update all members of the replica set to use WiredTiger, update the secondary members first. Then step down the primary, and update the stepped-down member.
Upgrade a Sharded Cluster to 3.0¶
Only upgrade sharded clusters to 3.0 if all members of the cluster are currently running instances of 2.6. The only supported upgrade path for sharded clusters running 2.4 is via 2.6. The upgrade process checks all components of the cluster and will produce warnings if any component is running version 2.4.
Considerations¶
The upgrade process does not require any downtime. However, while you upgrade the sharded cluster, ensure that clients do not make changes to the collection meta-data. For example, during the upgrade, do not do any of the following:
sh.enableSharding()
sh.shardCollection()
sh.addShard()
db.createCollection()
db.collection.drop()
db.dropDatabase()
- any operation that creates a database
- any other operation that modifies the cluster metadata in any way. See Sharding Reference for a complete list of sharding commands. Note, however, that not all commands on the Sharding Reference page modifies the cluster meta-data.
Upgrade Sharded Clusters¶
Optional but Recommended. As a precaution, take a backup of the
config
database before upgrading the sharded cluster.
Disable the Balancer.¶
Turn off the balancer in the sharded cluster, as described in Disable the Balancer.
Upgrade the cluster’s meta data.¶
Start a single 3.0 mongos
instance with
the configDB
pointing to the cluster’s config servers and with
the --upgrade
option.
To run a mongos
with the --upgrade
option, you
can upgrade an existing mongos
instance to 3.0, or if you
need to avoid reconfiguring a production mongos
instance,
you can use a new 3.0 mongos
that can reach all the config
servers.
To upgrade the meta data, run:
You can include the --logpath
option
to output the log messages to a file instead of the standard
output. Also include any other options required to start
mongos
instances in your cluster, such as
--sslOnNormalPorts
or
--sslPEMKeyFile
.
The 3.0 mongos
will output informational log
messages.
The mongos
will exit upon completion of the
--upgrade
process.
The upgrade will prevent any chunk moves or splits from occurring during the upgrade process. If the data files have many sharded collections or if failed processes hold stale locks, acquiring the locks for all collections can take seconds or minutes. Watch the log for progress updates.
Ensure mongos --upgrade
process completes successfully.¶
The mongos
will exit upon completion of the meta data
upgrade process. If successful, the process will log the following
messages:
After a successful upgrade, restart the mongos
instance.
If mongos
fails to start, check the log for more
information.
If the mongos
instance loses its connection to the config
servers during the upgrade or if the upgrade is otherwise
unsuccessful, you may always safely retry the upgrade.
Upgrade the config servers.¶
After you have successfully upgraded all mongos
instances, upgrade all 3 mongod
config server instances,
leaving the first config server listed in the
mongos --configdb
argument to upgrade last.
Upgrade the shards.¶
Upgrade each shard, one at a time, upgrading the mongod
secondaries before running replSetStepDown
and upgrading
the primary of each shard.
Re-enable the balancer.¶
Once the upgrade of sharded cluster components is complete, Re-enable the balancer.
Change Sharded Cluster Storage Engine to WiredTiger¶
For a sharded cluster in MongoDB 3.0, you can choose to update the shards to use WiredTiger storage engine and have the config servers use MMAPv1. If you update the config servers to use WiredTiger, you must update all three config servers to use WiredTiger.
Considerations¶
Before enabling the new WiredTiger storage engine, ensure that all replica set/sharded cluster members are running at least MongoDB version 2.6.8, and preferably version 3.0.0 or newer.
Note
You may safely continue to use MMAPv1 for the config servers even if the rest of your cluster is using WiredTiger
Change Shards to Use WiredTiger¶
To change the storage engine for the shards to WiredTiger, refer to the procedures in Change Storage Engine to WiredTiger for replica sets and Change Storage Engine to WiredTiger for standalone mongod as appropriate for your shards.
Change Config Server to Use WiredTiger¶
For a sharded cluster in MongoDB 3.0, you may continue to use MMAPv1 for the config servers even if the shards use WiredTiger; if, however, you decide to change the config servers to use the WiredTiger storage engine, you must change all three config servers to use WiredTiger.
Note
During this process, only two config servers will be running at any given time to ensure that the sharded cluster’s metadata is read only.
As a reminder, you may safely continue to use MMAPv1 for the config servers even if the rest of your cluster is using WiredTiger.
Disable the Balancer.¶
Turn off the balancer in the sharded cluster, as described in Disable the Balancer.
Restart the second config server with WiredTiger.¶
Specify wiredTiger
as the --storageEngine
and the newly
created WiredTiger data directory as the --dbpath
as well
as any additional options as appropriate.
You can also specify the options in a configuration file. To specify the storage engine, use
the new storage.engine
setting.
Upload the exported data using mongorestore
to the second config server.¶
Specify additional options as appropriate. See
mongorestore
for available options.
Shut down the second config server.¶
Restart the third config server.¶
Restart the third config server with WiredTiger.¶
Specify wiredTiger
as the --storageEngine
and the newly
created WiredTiger data directory as the --dbpath
as well
as any additional options as appropriate.
You can also specify the options in a configuration file. To specify the storage engine, use
the new storage.engine
setting.
Upload the exported data using mongorestore
to the third config server.¶
Specify additional options as appropriate. See
mongorestore
for available options
Restart the first config server with WiredTiger.¶
Specify wiredTiger
as the --storageEngine
and the newly
created WiredTiger data directory as the --dbpath
as well
as any additional options as appropriate.
You can also specify the options in a configuration file. To specify the storage engine, use
the new storage.engine
setting.
Upload the exported data using mongorestore
to the first config server.¶
Specify additional options as appropriate. See
mongorestore
for available options
Enable writes to the sharded cluster’s metadata.¶
Restart the second config server, specifying WiredTiger as the
--storageEngine
and the newly created WiredTiger data
directory as the --dbpath
. Specify additional options as
appropriate.
You can also specify the options in a configuration file. To specify the storage engine, use
the new storage.engine
setting.
Once all three config servers are up, the sharded cluster’s metadata is available for writes.
Re-enable the balancer.¶
Once all three config servers are up and running with WiredTiger, Re-enable the balancer.
Upgrade Existing MONGODB-CR
Users to Use SCRAM-SHA-1
¶
After upgrading the binaries, see Upgrade to SCRAM for details on
SCRAM-SHA-1
upgrade scenarios.
General Upgrade Procedure¶
Except as described on this page, moving between 2.6 and 3.0 is a drop-in replacement:
Stop the existing mongod
instance.¶
For example, on Linux, run 2.6 mongod
with the
--shutdown
option as follows:
Replace /var/mongod/data
with your MongoDB dbPath
.
See also the Stop mongod Processes for alternate methods of
stopping a mongod
instance.