Upgrade Requirements for MongoDB Versions

Upgrade Requirements for MongoDB 3.4

If you’re running a version of MongoDB before MongoDB 3.2, you must first upgrade to MongoDB 3.2 before upgrading to MongoDB 3.4.

With MongoDB version 3.4, you should be aware of the fact that:

Before upgrading, you must do the following:

Upgrade Requirements for MongoDB 3.2

If you’re running a version of MongoDB before MongoDB 3.0, you must first upgrade to MongoDB 3.0 before upgrading to MongoDB 3.2.

With MongoDB version 3.2, you should be aware of the fact that:

Before upgrading, you must do the following:

Upgrade Requirements for MongoDB 3.0

If you’re running a version of MongoDB before MongoDB 2.6, you must first upgrade to MongoDB 2.6 before upgrading to MongoDB 3.0.

Once a mLab-hosted deployment is running MongoDB 3.0, it cannot be downgraded to an earlier release version. Before upgrading, we strongly recommend testing the connectivity of your entire stack on a MongoDB 3.0 deployment with a SCRAM-SHA-1 authSchema, such as a mLab-hosted 3.0 Shared Cluster deployment.

With MongoDB version 3.0, you should be aware of the fact that:

Before upgrading, you must do the following:

  1. Review the full list of 3.0 changes that can affect compatibility with older version of MongoDB.
  2. Upgrade all connecting apps to use a MongoDB 3.0 and SCRAM-SHA-1-compatible driver (Moped/Mongoid users - see note below).

Moped (used by Mongoid 4 and below), is not compatible with MongoDB version 3.0 because it does not support SCRAM-SHA-1 authentication. If you’re using Mongoid, you must upgrade to Mongoid 5 before upgrading your mLab-hosted deployment to 3.0.

Upgrade Requirements for MongoDB 2.6

If you’re running a version of MongoDB before MongoDB 2.4, you must first upgrade to MongoDB 2.4 before upgrading to MongoDB 2.6.

With MongoDB version 2.6, you should be aware of the fact that:

Before upgrading, you must do the following:

  1. Review the full list of 2.6 changes that can affect the compatability with older version of MongoDB.
  2. Run the preliminary upgrade check to verify compatibility of your data set with MongoDB 2.6 (see below).
  3. Assess and resolve all issues identified by your review and by this upgrade check.

When you initiate an upgrade to MongoDB 2.6 from the mLab management portal, not only will we upgrade the binaries that are running your mongod processes, we will also complete the authorization user schema upgrade.

Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4. If you absolutely need to downgrade back to version 2.4, you will need to contact our support team to help execute the steps outlined in MongoDB’s documentation for downgrading from 2.6.

How to run the preliminary 2.6 preparedness check

This command can be very taxing on your deployment as it performs collection scans against all collections. As such, you should consider running this preparedness check against either a staging environment or a secondary node on your production environment. We strongly recommend that you read the full documentation on this preparedness check before proceeding.

IMPORTANT NOTE: You need to use the mongo shell from MongoDB version 2.6.x to run the check, even though your deployment is not yet on 2.6.x.

(Installation instructions from MongoDB Inc.)

… on a Sandbox or for-pay Shared Single-node plan

  1. Connect to your database using the mongo shell with a command similar to this:

     % mongo ds012345.mlab.com:56789/mydb -u dbuser -p dbpassword
    
  2. Run the check

     > db.upgradeCheck()
    

… on a for-pay Shared Cluster plan

  1. Connect to your database on a secondary node using the mongo shell with a command similar to this:

     % mongo ds012345-a0.mlab.com:56789/mydb -u dbuser -p dbpassword
    
  2. Run the check

     > rs.slaveOk()
     > db.upgradeCheck()
    

… on a Dedicated Single-node plan

  1. Connect to the “admin” database using the mongo shell with a command similar to this:

     % mongo ds012345-a0.mlab.com:56789/admin -u adminuser -p adminpassword
    
  2. Run the check which cycles through all databases:

     > db.upgradeCheckAllDBs()
    

… on a Dedicated Cluster plan

  1. Connect to the “admin” database on a secondary node using the mongo shell with a command similar to this:

     % mongo ds012345-a0.mlab.com:56789/admin -u adminuser -p adminpassword
    
  2. Run the check which cycles through all databases:

     > rs.slaveOk()
     > db.upgradeCheckAllDBs()
    

Upgrade Requirements for MongoDB 2.4

If you are upgrading from MongoDB 2.0, you should also be reviewing the Upgrade Requirements for MongoDB 2.2.

With MongoDB version 2.4, there are a couple of potentially breaking changes that should be highlighted:

To resolve duplicate usernames (a change to your application code will be required):

  1. Connect to the database using the mongo shell with a command similar to this:

     % mongo ds012345.mlab.com:56789/dbname -u dbuser -p dbpassword
    
  2. Add a new user to the database that has a different username as that of the duplicate user:

     > db.addUser('username', 'password')
    
  3. Update your application’s connection code to use the new user you just created.
  4. If your app requires a restart to start using to the new database credentials, do that now.
  5. Verify that your app is able to authenticate to your database and is functioning normally.
  6. Delete the old duplicate users:

      > db.removeUser('old_duplicate_username')
    
  7. Add a unique index constraint to your system.users collection. See below for instructions.

Alternate steps: If for some reason you need to avoid a change to your application’s connection code, you can follow these alternate instructions instead. However, be forewarned that this process will involve a brief period of time where your application will not be able to authenticate to your database:

  1. Connect to the database using the mongo shell with a command similar to this:

     % mongo ds012345.mlab.com:56789/dbname -u dbuser -p dbpassword
    
  2. Delete the old duplicate users:

     > db.removeUser('duplicate_username')
    
  3. Add a user back to the database using the same username and password that your application is using to authenticate to your database:

     > db.addUser('username', 'password')
    
  4. Verify that your app is able to authenticate to your database and is functioning normally.
  5. Add a unique index constraint to your system.users collection. See below for instructions.

Prevent duplicate users before you upgrade

If you cannot upgrade to 2.4 right away, we recommend that you take the steps to ensure duplicate users are not created before your database is upgraded. To do this, you’ll need to add a unique index contraint on your system.users collection:

> db.system.users.ensureIndex({"user" : 1}, {"unique" : true})

Not sure what database credentials your application is using?

For those of you who are using mLab as an add-on with one of our partners and are having trouble figuring out what credentials your application is actually using, it might be because you are using an environment variable to authenticate to your mLab database.

For example, if you are using the mLab add-on through Heroku, your application’s connection code is probably using the MONGODB_URI environment variable. If so, you can install and use the Heroku command line tool to fetch the value of this environment variable with the following command:

heroku config --app your_heroku_app_name | grep MONGODB_URI

Using the pattern below, you can figure out your username and password with the result from the command above:

mongodb://username:password@host:port/database_name

Upgrade Requirements for MongoDB 2.2

Driver Requirements

MongoDB version 2.2 made changes to the way clients talk to the server, so it is critical that you make sure you are using the correct driver prior to upgrading.

Major 10gen-supported drivers that are compatible with 2.2 are as follows:

Of course, these are just minimum versions. We recommend running the latest version of you driver to get any bug fixes or improvements they may include.

Limits and Thresholds

Restriction on Collection Names

Collection names should begin with an underscore or a letter character, and cannot:

Nested Depth for BSON Documents

MongoDB supports no more than 100 levels of nesting for BSON documents.