In this blog post, I will share the necessary steps for a smooth upgrade from MongoDB (or Percona Server MongoDB) standalone version 3.4 to 3.6. I have plans to publish new versions for sharding and replica-set too. For now, let’s stick with the steps for the standalone.
Upgrade Recommendations and Checklists
Create backup
Optional but Recommended. Create a backup of your database.
Preparedness
Before beginning your upgrade, see the Compatibility Changes in MongoDB 3.6 document to ensure that your applications and deployments are compatible with MongoDB 3.6. Resolve the incompatibilities in your deployment before starting the upgrade. Before upgrading MongoDB, always test your application in a staging environment before deploying the upgrade to your production environment.
Pre-requisites
The 3.4 instances must have featureCompatibilityVersion
set to 3.4
. To check featureCompatibilityVersion
:
1 |
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) |
The operation should return a result that includes "featureCompatibilityVersion": "3.4"
. To set or update, run the following command:
1 |
db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } ) |
Upgrade Process
1. Download the binaries (For PSMDB: https://www.percona.com/downloads/)
2. Shut down your mongod instance.
Replace the existing binary with the 3.6 mongod binary. Restart mongod.
3. Enable backward-incompatible 3.6 features.
Run the setFeatureCompatibilityVersion
command against the admin
database:
1 |
db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } ) |
Note: It is recommended that after upgrading, you allow your deployment to run without enabling these features for a burn-in period to ensure the likelihood of downgrade is minimal. When you are confident that the likelihood of downgrade is minimal, enable these features.
This command must perform writes to an internal system collection. If for any reason the command does not complete successfully, you can safely retry the command as the operation is idempotent.
Downgrade
Before downgrading the binaries, you must downgrade the feature compatibility version and remove any 3.6 features incompatible with 3.4 versions as outlined below. These steps are necessary only if featureCompatibilityVersion
has ever been set to "3.6"
.
1. Downgrade Feature Compatibility Version
1 |
db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } ) |
2. Remove Backwards Incompatible Persisted Features
Remove all persisted features that are incompatible with 3.4. For example, if you have defined any view definitions, document validators, and partial index filters that use 3.6 query features such as $jsonSchema or $expr, you must remove them.
3. Download the latest 3.4 binaries (For PSMDB: https://www.percona.com/downloads/)
4. Restart with the latest 3.4 mongod instance.
Shut down your mongod
instance. Replace the existing binary with the downloaded mongod
binary and restart.
- Perform a clean shut down of the
mongod
process.
NOTE
If you do not perform a clean shut down, errors may result in that prevent the mongod
process from starting.Forcibly terminating the mongod
process may cause inaccurate results for db.collection.count()
and db.stats()
as well as lengthen startup time the next time that the mongod
process is restarted.Invoking sudo service mongod stop
does not guarantee a clean shutdown. This service
script forceably stops the mongod
process if it takes longer than five minutes to shut down.
- Replace the 3.6 binary with the 3.4 binary.
- Start the 3.4
mongod
process.
And that’s it. Having a single instance is not a recommended architecture, however, I do see them in use for testing purposes on QA environments so I think it is worth to be aware of it. See you next!
References:
https://docs.mongodb.com/manual/release-notes/3.6-upgrade-standalone/
https://docs.mongodb.com/manual/release-notes/3.6-downgrade-standalone/