So, now you need to upgrade your MongoDB cluster…

Your MongoDB cluster has been running fine for years on 4.4 or 6.0. Then the version goes end of life, a CVE shows up in an audit, or a new feature needs 8.0, and the MongoDB upgrade lands on your desk.

The upgrade itself is not hard. Knowing everything you have to check before, during and after each step is the hard part. We see the same pattern in support again and again: the upgrade stops halfway because one small requirement was buried in a page nobody opened.

Why a MongoDB upgrade hurts

MongoDB upgrades one major version at a time. Going from 4.4 to 8.0 means four hops (4.4 to 5.0, 6.0, 7.0 and 8.0), and each hop has its own upgrade page, its own compatibility notes and its own rollback rules. A few of the things that stop an upgrade halfway:

• featureCompatibilityVersion (FCV). The next hop fails if FCV still points at the previous version. And once you raise it, a binary downgrade is no longer possible.
• Packages and repositories. Each major has its own repository. A pinned or held package silently stays on the old version, and mongosh or the database tools do not always follow the server.
• Drivers. An old driver that still sends legacy opcodes stops working on 6.0, and the error shows up in the application, not in the database.
• Backup and monitoring. Percona Backup for MongoDB (PBM) and PMM have their own supported version ranges, so the backup agent can fall behind the server you just upgraded.
• Security. The version you land on can still carry known CVEs, and not every MongoDB fix has a Percona Server for MongoDB build in every series.

 

None of this is secret. It is spread across release notes, compatibility pages, driver tables and the docs for each tool, and you have to read all of it for every hop.

A MongoDB upgrade plan built from the official docs

I built the MongoDB Upgrade Roadmap to put that documentation in one place. You tell it the current version, the target version and how the cluster runs. It returns every hop with:

1. Pre-flight checks. Each one has the command to run, where to run it (primary, each mongod, a mongos) and the output to expect.
2. The official upgrade steps for your topology and package manager (apt or yum), or for the Percona Operator for MongoDB on Kubernetes.
3. The rollback window. What you can still undo before you raise FCV, and what you cannot undo after.
4. Post-upgrade checks and behaviour changes. What changes for applications, monitoring and backups once you land.

It covers Percona Server for MongoDB and MongoDB Community, from 3.0 to 9.0, including the 8.2 and 8.3 minor releases. You can add your drivers, PBM, PMM and Operator versions, CPU and OS, and the plan checks them against each hop.

Three rules shaped it:

• It never connects to your cluster. It is a static page, and nothing you type leaves your browser.
• Every check and step links to the exact section of the official docs it came from. Where the docs contradict each other, the plan says so instead of picking a side.
• Lab results are marked. We ran the main paths (replica sets on apt and yum, patch upgrades and the Operator) on lab clusters, and those items say “Tested on a lab cluster”.

Example: upgrade Percona Server for MongoDB 6.0 to 8.3

Pick Percona Server for MongoDB 6.0.29-23 as the current version, 8.3.13-4 as the target, a replica set and apt. The plan shows the path 6.0 to 7.0 to 8.0 to 8.3, three hops, with one tab per hop.

Each hop splits into Before, Steps, After, Rollback and What changes. For the 6.0 to 7.0 hop that is 23 pre-flight checks, 4 procedure steps and 7 post-upgrade checks. Each check has a checkbox, so you can track where you are, and Copy as Markdown puts the whole plan in your change ticket.

MongoDB upgrade FAQ

Can I upgrade MongoDB from 4.4 to 8.0 directly?

No. MongoDB supports upgrades one major version at a time, so 4.4 to 8.0 goes through 5.0, 6.0 and 7.0, and you set FCV at the end of each hop. The 8.2 and 8.3 minor releases follow their own documented paths.

When should I set featureCompatibilityVersion?

After every member runs the new binaries and the cluster works as expected. Before that you can still go back to the previous binaries; after it, a downgrade is much harder.

Does the roadmap connect to my database?

No. The page runs in your browser and never contacts your cluster. You type the versions, and it builds the plan from the official documentation it ships with.

Before you start your MongoDB upgrade

An upgrade that stops halfway is worse than one that never started: one member on the new binaries, FCV on the old version and a maintenance window running out. A plan that lists every requirement for every hop up front prevents that.

The plan is not a substitute for testing. Run it on a staging cluster first, with the same versions, drivers and tools you run in production.

If an in-place upgrade does not fit your window, you can migrate instead. Percona ClusterSync for MongoDB (PCSM) clones the data to a new cluster on the target version and keeps it in sync through change streams until you switch the applications over. Its compatibility matrix supports 6.0 to 7.0 or 8.0, and 7.0 to 8.0, so a 6.0 cluster can reach 8.0 in one step. Read the limitations first: users and roles are not synchronized, PCSM does not check FCV on the target, and there is no reverse sync to fall back on.

The page is at zelmario.github.io/mongodb-upgrade-roadmap, and the source and knowledge base are on GitHub. If you find a check that is missing or wrong, open an issue or a pull request. Every fix makes the next upgrade easier for someone else.

The post So, now you need to upgrade your MongoDB cluster… appeared first on Percona.