Docs Menu
Docs Home
/
MongoDB Manual
/ /

Downgrade MongoDB from 2.6

On this page

  • Downgrade Recommendations and Checklist
  • Downgrade 2.6 User Authorization Model
  • Downgrade Updated Indexes
  • Downgrade MongoDB Processes

Before you attempt any downgrade, familiarize yourself with the content of this document, particularly the Downgrade Recommendations and Checklist and the procedure for downgrading sharded clusters.

When downgrading, consider the following:

Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4. If you created text or 2dsphere indexes while running 2.6, you can only downgrade to MongoDB 2.4.10 or later.

Follow the downgrade procedures:

If you have upgraded to the 2.6 user authorization model, you must first downgrade the user authorization model to 2.4 before before downgrading MongoDB 2.6 to 2.4.

  • For a replica set, it is only necessary to run the downgrade process on the primary as the changes will automatically replicate to the secondaries.

  • For sharded clusters, although the procedure lists the downgrade of the cluster's authorization data first, you may downgrade the authorization data of the cluster or shards first.

  • You must have the admin.system.backup_users and admin.system.new_users collections created during the upgrade process.

  • Important. The downgrade process returns the user data to its state prior to upgrading to 2.6 authorization model. Any changes made to the user/role data using the 2.6 users model will be lost.

To downgrade the authorization model, you must connect as a user with the following privileges:

{ resource: { db: "admin", collection: "system.new_users" }, actions: [ "find", "insert", "update" ] }
{ resource: { db: "admin", collection: "system.backup_users" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.users" }, actions: [ "find", "remove", "insert"] }
{ resource: { db: "admin", collection: "system.version" }, actions: [ "find", "update" ] }

If no user exists with the appropriate privileges, create an authorization model downgrade user:

1

Connect and authenticate as a user with userAdminAnyDatabase.

2

Using the db.createRole() method, create a role with the required privileges.

use admin
db.createRole(
{
role: "downgradeAuthRole",
privileges: [
{ resource: { db: "admin", collection: "system.new_users" }, actions: [ "find", "insert", "update" ] },
{ resource: { db: "admin", collection: "system.backup_users" }, actions: [ "find" ] },
{ resource: { db: "admin", collection: "system.users" }, actions: [ "find", "remove", "insert"] },
{ resource: { db: "admin", collection: "system.version" }, actions: [ "find", "update" ] }
],
roles: [ ]
}
)
3

Create a user and assign the user the downgradeRole.

use admin
db.createUser(
{
user: "downgradeAuthUser",
pwd: "somePass123",
roles: [ { role: "downgradeAuthRole", db: "admin" } ]
}
)

Note

Instead of creating a new user, you can also grant the role to an existing user. See db.grantRolesToUser() method.

4

Authenticate as the newly created user.

use admin
db.auth( "downgradeAuthUser", "somePass123" )

The method returns 1 upon successful authentication.

The following downgrade procedure requires <database>.system.users collections used in version 2.4. to be intact for non-admin databases.

1

Connect and authenticate to the mongod instance for a single deployment or a mongos for a sharded cluster with the appropriate privileges. See Access Control Prerequisites for details.

2

Copy all documents in the admin.system.users collection to the admin.system.new_users collection:

db.getSiblingDB("admin").system.users.find().forEach( function(userDoc) {
status = db.getSiblingDB("admin").system.new_users.save( userDoc );
if (status.hasWriteError()) {
print(status.writeError);
}
}
);
3
db.getSiblingDB("admin").system.version.update(
{ _id: "authSchema" },
{ $set: { currentVersion: 2 } }
);

The method returns a WriteResult() object with the status of the operation. Upon successful update, the WriteResult() object should have "nModified" equal to 1.

4
db.getSiblingDB("admin").system.users.remove( {} )

The method returns a WriteResult() object with the number of documents removed in the "nRemoved" field.

5

Copy all documents from the admin.system.backup_users, created during the 2.6 upgrade, to admin.system.users.

db.getSiblingDB("admin").system.backup_users.find().forEach(
function (userDoc) {
status = db.getSiblingDB("admin").system.users.insert( userDoc );
if (status.hasWriteError()) {
print(status.writeError);
}
}
);
6
db.getSiblingDB("admin").system.version.update(
{ _id: "authSchema" },
{ $set: { currentVersion: 1 } }
)

For a sharded cluster, repeat the downgrade process by connecting to the primary replica set member for each shard.

Note

The cluster's mongos instances will fail to detect the authorization model downgrade until the user cache is refreshed. You can run invalidateUserCache on each mongos instance to refresh immediately, or you can wait until the cache is refreshed automatically at the end of the user cache invalidation interval. To run invalidateUserCache, you must have privilege with invalidateUserCache action, which is granted by userAdminAnyDatabase and hostManager roles.

The downgrade process returns the user data to its state prior to upgrading to 2.6 authorization model. Any changes made to the user/role data using the 2.6 users model will be lost.

If you have version 2 text indexes (i.e. the default version for text indexes in MongoDB 2.6), drop the version 2 text indexes before downgrading MongoDB. After the downgrade, enable text search and recreate the dropped text indexes.

To determine the version of your text indexes, run db.collection.getIndexes() to view index specifications. For text indexes, the method returns the version information in the field textIndexVersion. For example, the following shows that the text index on the quotes collection is version 2.

{
"v" : 1,
"key" : {
"_fts" : "text",
"_ftsx" : 1
},
"name" : "quote_text_translation.quote_text",
"ns" : "test.quotes",
"weights" : {
"quote" : 1,
"translation.quote" : 1
},
"default_language" : "english",
"language_override" : "language",
"textIndexVersion" : 2
}

If you have version 2 2dsphere indexes (i.e. the default version for 2dsphere indexes in MongoDB 2.6), drop the version 2 2dsphere indexes before downgrading MongoDB. After the downgrade, recreate the 2dsphere indexes.

To determine the version of your 2dsphere indexes, run db.collection.getIndexes() to view index specifications. For 2dsphere indexes, the method returns the version information in the field 2dsphereIndexVersion. For example, the following shows that the 2dsphere index on the locations collection is version 2.

{
"v" : 1,
"key" : {
"geo" : "2dsphere"
},
"name" : "geo_2dsphere",
"ns" : "test.locations",
"sparse" : true,
"2dsphereIndexVersion" : 2
}

The following steps outline the procedure to downgrade a standalone mongod from version 2.6 to 2.4.

  1. Download binaries of the latest release in the 2.4 series from the MongoDB Download Page. See Install MongoDB for more information.

  2. Shut down your mongod instance. Replace the existing binary with the 2.4 mongod binary and restart mongod.

The following steps outline a "rolling" downgrade process for the replica set. The "rolling" downgrade process minimizes downtime by downgrading the members individually while the other members are available:

1

For each secondary in a replica set:

First, shut down the mongod, then replace these binaries with the 2.4 binary and restart mongod. See Stop mongod Processes for instructions on safely terminating mongod processes.

Wait for the member to recover to SECONDARY state before upgrading the next secondary.

To check the member's state, use the rs.status() method in the mongo shell.

2

Use rs.stepDown() in the mongo shell to step down the primary and force the normal failover procedure.

rs.stepDown()
rs.stepDown() expedites the failover procedure and is
preferable to shutting down the primary directly.
3

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 2.4 binary and start the new instance.

Replica set failover is not instant but will render the set unavailable to writes and interrupt reads until the failover process completes. Typically this takes 10 seconds or more. You may wish to plan the downgrade during a predetermined maintenance window.

While the downgrade is in progress, you cannot make changes to the collection meta-data. For example, during the downgrade, do not do any of the following:

The downgrade procedure for a sharded cluster reverses the order of the upgrade procedure.

  1. Turn off the balancer in the sharded cluster, as described in Disable the Balancer.

  2. Downgrade each shard, one at a time. For each shard,

    1. Downgrade the mongod secondaries before downgrading the primary.

    2. To downgrade the primary, run replSetStepDown and downgrade.

  3. Downgrade all 3 mongod config server instances, leaving the first system in the mongos --configdb argument to downgrade last.

  4. Downgrade and restart each mongos, one at a time. The downgrade process is a binary drop-in replacement.

  5. Turn on the balancer, as described in Enable the Balancer.

Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4. If you have text or 2dsphere indexes, you can only downgrade to MongoDB 2.4.10 or later.

Except as described on this page, moving between 2.4 and 2.6 is a drop-in replacement:

1

For example, on Linux, run 2.6 mongod with the --shutdown option as follows:

mongod --dbpath /var/mongod/data --shutdown

Replace /var/mongod/data with your MongoDB dbPath. See also the Stop mongod Processes for alternate methods of stopping a mongod instance.

2

Ensure you start the 2.4 mongod with the same dbPath:

mongod --dbpath /var/mongod/data

Replace /var/mongod/data with your MongoDB dbPath.

Back

Upgrade User Authorization Data to 2.6 Format