Downgrade MongoDB from 2.6

Before you attempt any downgrade, familiarize yourself with the contentof this document, particularly the Downgrade Recommendations and Checklistand 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 versionearlier than MongoDB 2.4. If you created text or 2dsphereindexes while running 2.6, you can only downgrade to MongoDB 2.4.10 orlater.

Preparedness

Procedures

Follow the downgrade procedures:

Downgrade 2.6 User Authorization Model

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

Considerations

  • For a replica set, it is only necessary to run the downgrade processon the primary as the changes will automatically replicate tothe secondaries.
  • For sharded clusters, although the procedure lists the downgrade ofthe cluster’s authorization data first, you may downgrade theauthorization data of the cluster or shards first.
  • You must have the admin.system.backup_users andadmin.system.new_users collections created during the upgradeprocess.
  • Important. The downgrade process returns the user data to itsstate prior to upgrading to 2.6 authorization model. Any changesmade 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 withthe following privileges:

  1. { resource: { db: "admin", collection: "system.new_users" }, actions: [ "find", "insert", "update" ] }
  2. { resource: { db: "admin", collection: "system.backup_users" }, actions: [  "find" ] }
  3. { resource: { db: "admin", collection: "system.users" }, actions: [ "find", "remove", "insert"] }
  4. { 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 withuserAdminAnyDatabase.

Create a role with required privileges.

Using the db.createRole method, create arole with the required privileges.

  1. use admin
  2. db.createRole(
  3.   {
  4.     role: "downgradeAuthRole",
  5.     privileges: [
  6.       { resource: { db: "admin", collection: "system.new_users" }, actions: [ "find", "insert", "update" ] },
  7.       { resource: { db: "admin", collection: "system.backup_users" }, actions: [  "find" ] },
  8.       { resource: { db: "admin", collection: "system.users" }, actions: [ "find", "remove", "insert"] },
  9.       { resource: { db: "admin", collection: "system.version" }, actions: [ "find", "update" ] }
  10.     ],
  11.     roles: [ ]
  12.   }
  13. )

Create a user with the new role.

Create a user and assign the user the downgradeRole.

  1. use admin
  2. db.createUser(
  3.    {
  4.      user: "downgradeAuthUser",
  5.      pwd: "somePass123",
  6.      roles: [ { role: "downgradeAuthRole", db: "admin" } ]
  7.    }
  8. )

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.

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

The method returns 1 upon successful authentication.

Procedure

The following downgrade procedure requires <database>.system.userscollections used in version 2.4. to be intact for non-admindatabases.

Connect and authenticate to MongoDB instance.

Connect and authenticate to the mongod instance for asingle deployment or a mongos for a sharded cluster withthe appropriate privileges. See Access Control Prerequisitesfor details.

Create backup of 2.6 admin.system.users collection.

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

  1. db.getSiblingDB("admin").system.users.find().forEach( function(userDoc) {
  2.     status = db.getSiblingDB("admin").system.new_users.save( userDoc );
  3.     if (status.hasWriteError()) {
  4.         print(status.writeError);
  5.     }
  6.   }
  7. );

Update the version document for the authSchema.

  1. db.getSiblingDB("admin").system.version.update(
  2.    { _id: "authSchema" },
  3.    { $set: { currentVersion: 2 } }
  4. );

The method returns a WriteResult object with the statusof the operation.Upon successful update, the WriteResult object shouldhave "nModified" equal to 1.

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

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

The method returns a WriteResult object with the number ofdocuments 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 the2.6 upgrade, to admin.system.users.

  1. db.getSiblingDB("admin").system.backup_users.find().forEach(
  2.    function (userDoc) {
  3.       status = db.getSiblingDB("admin").system.users.insert( userDoc );
  4.       if (status.hasWriteError()) {
  5.           print(status.writeError);
  6.       }
  7.    }
  8. );

Update the version document for the authSchema.

  1. db.getSiblingDB("admin").system.version.update(
  2.    { _id: "authSchema" },
  3.    { $set: { currentVersion: 1 } }
  4. )

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

Note

The cluster’s mongos instances will fail to detect theauthorization model downgrade until the user cache is refreshed. Youcan run invalidateUserCache on each mongosinstance to refresh immediately, or you can wait until the cache isrefreshed automatically at the end of the user cacheinvalidation interval. To runinvalidateUserCache, you must have privilege withinvalidateUserCache action, which is granted byuserAdminAnyDatabase and hostManager roles.

Result

The downgrade process returns the user data to its state prior toupgrading to 2.6 authorization model. Any changes made to theuser/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 textindexes in MongoDB 2.6), drop the version 2 text indexes beforedowngrading MongoDB. After the downgrade, enable text search andrecreate the dropped text indexes.

To determine the version of your text indexes, rundb.collection.getIndexes() to view index specifications. Fortext indexes, the method returns the version information in the fieldtextIndexVersion. For example, the following shows that thetext index on the quotes collection is version 2.

  1. {
  2.    "v" : 1,
  3.    "key" : {
  4.       "_fts" : "text",
  5.       "_ftsx" : 1
  6.    },
  7.    "name" : "quote_text_translation.quote_text",
  8.    "ns" : "test.quotes",
  9.    "weights" : {
  10.       "quote" : 1,
  11.       "translation.quote" : 1
  12.    },
  13.    "default_language" : "english",
  14.    "language_override" : "language",
  15.    "textIndexVersion" : 2
  16. }

2dsphere Index Version Check

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

To determine the version of your 2dsphere indexes, rundb.collection.getIndexes() to view index specifications. For2dsphere indexes, the method returns the version information in the field2dsphereIndexVersion. For example, the following shows that the2dsphere index on the locations collection is version 2.

  1. {
  2.    "v" : 1,
  3.    "key" : {
  4.       "geo" : "2dsphere"
  5.    },
  6.    "name" : "geo_2dsphere",
  7.    "ns" : "test.locations",
  8.    "sparse" : true,
  9.    "2dsphereIndexVersion" : 2
  10. }

Downgrade MongoDB Processes

Downgrade 2.6 Standalone mongod Instance

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

Downgrade a 2.6 Replica Set

The following steps outline a “rolling” downgrade process for thereplica set. The “rolling” downgrade process minimizes downtime bydowngrading the members individually while the other members areavailable:

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 thesebinaries with the 2.4 binary andrestart mongod. See Stop mongod Processesfor instructions on safely terminating mongod processes.

Allow secondary to recover.

Wait for the member to recover to SECONDARY statebefore 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 tostep down the primary and force the normal failover procedure.

  1. 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 downand another member has assumed PRIMARY state, shut down theprevious primary and replace the mongod binary withthe 2.4 binary and start the new instance.

Replica set failover is not instant but will render the set unavailable towrites and interrupt reads until the failover processcompletes. Typically this takes 10 seconds or more. You may wish toplan 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 thecollection meta-data. For example, during the downgrade, donot do any of the following:

Procedure

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

  • Turn off the balancer in thesharded cluster, as described inDisable the Balancer.
  • Downgrade each shard, one at a time. For each shard,
    • Downgrade the mongod secondaries before downgradingthe primary.
    • To downgrade the primary, run replSetStepDown anddowngrade.
  • Downgrade all 3 mongod config server instances, leavingthe first system in the mongos —configdb argument todowngrade last.
  • Downgrade and restart each mongos, one at a time. Thedowngrade process is a binary drop-in replacement.
  • Turn on the balancer, as described inEnable the Balancer.

Downgrade Procedure

Once upgraded to MongoDB 2.6, you cannot downgrade to any versionearlier 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 adrop-in replacement:

Stop the existing mongod instance.

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

  1. mongod --dbpath /var/mongod/data --shutdown

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

Start the new mongod instance.

Ensure you start the 2.4 mongod with the samedbPath:

  1. mongod --dbpath /var/mongod/data

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