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.

Downgrade Recommendations and Checklist

When downgrading, consider the following:

Downgrade Path

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.

Preparedness

Remove or downgrade version 2 text indexes before downgrading MongoDB 2.6 to 2.4.
Remove or downgrade version 2 2dsphere indexes before downgrading MongoDB 2.6 to 2.4.
Downgrade 2.6 User Authorization Model. If you have upgraded to the 2.6 user authorization model, you must downgrade the user model to 2.4 before downgrading MongoDB 2.6 to 2.4.

Procedures

Follow the downgrade procedures:

To downgrade sharded clusters, see Downgrade a 2.6 Sharded Cluster.
To downgrade replica sets, see Downgrade a 2.6 Replica Set.
To downgrade a standalone MongoDB instance, see Downgrade 2.6 Standalone mongod Instance.

Downgrade 2.6 User Authorization Model

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.

Considerations

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.

Access Control Prerequisites

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:

Connect as user with privileges to manage users and roles.

Connect and authenticate as a user with userAdminAnyDatabase.

Create a role with required privileges.

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: [ ]
  }
)

Create a user with the new role.

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.

Authenticate as the new user.

Authenticate as the newly created user.

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

The method returns 1 upon successful authentication.

Procedure

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

Connect and authenticate to MongoDB instance.

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.

Create backup of 2.6 `admin.system.users` collection.

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);
    }
  }
);

Update the version document for the `authSchema`.

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.

Remove existing documents from the `admin.system.users` collection.

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

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

Copy documents from the `admin.system.backup_users` collection.

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);
      }
   }
);

Update the version document for the `authSchema`.

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.

Result

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.

Downgrade Updated Indexes

Text Index Version Check

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
}

`2dsphere` Index Version Check

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
}

Downgrade MongoDB Processes

Downgrade 2.6 Standalone `mongod` Instance

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

Download binaries of the latest release in the 2.4 series from the MongoDB Download Page. See Install MongoDB for more information.
Shut down your mongod instance. Replace the existing binary with the 2.4 mongod binary and restart mongod.

Downgrade a 2.6 Replica Set

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:

Downgrade each secondary member, one at a time.

For each secondary in a replica set:

Replace and restart secondary `mongod` instances.

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.

Allow secondary to recover.

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.

Step down the primary.

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.

Replace and restart former primary `mongod`.

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.

Downgrade a 2.6 Sharded Cluster

Requirements

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:

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 meta-data 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.

Procedure

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

Turn off the balancer in the sharded cluster, as described in Disable the Balancer.
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.
Downgrade all 3 mongod config server instances, leaving the first system in the mongos --configdb argument to downgrade last.
Downgrade and restart each mongos, one at a time. The downgrade process is a binary drop-in replacement.
Turn on the balancer, as described in Enable the Balancer.

Downgrade Procedure

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:

Stop the existing `mongod` instance.

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.

Start the new `mongod` instance.

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

Release Notes for MongoDB 2.4

Downgrade MongoDB from 2.6.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Downgrade Recommendations and Checklist

Downgrade Path

Preparedness

Procedures

Downgrade 2.6 User Authorization Model

Considerations

Access Control Prerequisites

Connect as user with privileges to manage users and roles.

Create a role with required privileges.

Create a user with the new role.

Note

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

Authenticate as the new user.

Procedure

Connect and authenticate to MongoDB instance.

Create backup of 2.6 admin.system.users collection.

Update the version document for the authSchema.

Remove existing documents from the admin.system.users collection.

Copy documents from the admin.system.backup_users collection.

Update the version document for the authSchema.

Note

Result

Downgrade Updated Indexes

Text Index Version Check

2dsphere Index Version Check

Downgrade MongoDB Processes

Downgrade 2.6 Standalone mongod Instance

Downgrade a 2.6 Replica Set

Downgrade each secondary member, one at a time.

Replace and restart secondary mongod instances.

Allow secondary to recover.

Step down the primary.

Replace and restart former primary mongod.

Downgrade a 2.6 Sharded Cluster

Requirements

Procedure

Downgrade Procedure

Stop the existing mongod instance.

Start the new mongod instance.

Downgrade MongoDB from 2.6

Create backup of 2.6 `admin.system.users` collection.

Update the version document for the `authSchema`.

Remove existing documents from the `admin.system.users` collection.

Copy documents from the `admin.system.backup_users` collection.

Update the version document for the `authSchema`.

`2dsphere` Index Version Check

Downgrade 2.6 Standalone `mongod` Instance

Replace and restart secondary `mongod` instances.

Replace and restart former primary `mongod`.

Stop the existing `mongod` instance.

Start the new `mongod` instance.