You were assigned one of the most common, yet feared, tasks in the life of a database administrator:
Upgrades are needed for many reasons, whether to fix an existing bug or to keep the environment under support and eligible to receive security fixes. Either way, the task is yours.
The binary swap is the easy part. The hard part is everything before it:
A major upgrade in MongoDB moves one release at a time, regardless of the jump you plan. For example: “Going from 6.0 to 8.0”
So the homework is not done once. It is done per step, and for every step the checklist looks something like this:
mongod.conf and every setParameter against what was removed or renamed.None of this is hard per se. It is just long, tedious, easy to get wrong, and different for every version step. And there was no single command that answered the real question:
Is this deployment ready for the upgrade? If not, what should I fix first?
UCFM (Upgrade Checker For MongoDB) tells you whether a MongoDB or Percona Server for MongoDB deployment is ready to upgrade, and what to fix first.
If you have worked with MySQL, the idea may sound familiar: That’s because ucfm is heavily inspired by MySQL Shell’s upgrade checker, util.checkForServerUpgrade().
MySQL DBAs have had that answer for years.
The value is not in any single check. It is in having one place that knows every change between two versions, applies all of them to your deployment, and gives you a short list of things to fix.
That was the idea behind it: a tool that tells you what is right and what is wrong in your environment, and answers that same question one upgrade step at a time.
If you are one step earlier and still deciding which path to take, allow me to recommend the MongoDB Upgrade Roadmap; it can help you with the upgrade steps.
ucfm is a read-only tool that works by checking facts from every member it can reach on your deployment.
You point it at one node, and it discovers the rest of the replica set, or the config servers, shards and mongos. Then it runs three kinds of checks:
At the end of the check, it will generate a list with the findings and recommended actions.
Worth mentioning that ucfm does not upgrade anything. It reads and reports; the upgrade is still yours.
What it does give you is the answer to the question from the beginning of this post. Before the maintenance window, you know what could break and where.
One command downloads the latest release, verifies its checksum and installs ucfm into /usr/local/bin (or ~/.local/bin when you are not root). Running it again upgrades.
curl -fsSL https://raw.githubusercontent.com/jenunes/ucfm/main/install.sh | bash
The tool needs clusterMonitor, readAnyDatabase and a small role that can read users, roles and view definitions; for that we create a custom role ucfmViewSecurity which holds the necessary permissions so you can drop it afterwards if you prefer:
use admin
db.createRole({
role: "ucfmViewSecurity",
privileges: [
{ resource: { cluster: true }, actions: ["viewUser"] },
{ resource: { db: "", collection: "" }, actions: ["viewUser", "viewRole"] },
{ resource: { db: "", collection: "system.views" }, actions: ["find"] }
],
roles: []
})Then create the user granting the necessary permissions:
use admin
db.createUser({
user: "ucfm",
pwd: passwordPrompt(),
roles: ["clusterMonitor", "readAnyDatabase", "ucfmViewSecurity"]
})Note: On a sharded cluster, create it through a mongos and also on the primary of every shard. ucfm connects to shard members directly, and they only accept shard-local users. If you forget one, it warns you and names the shard.
Point --uri at any replica set member, or at a mongos(if sharded cluster), and name the target version:
ucfm check --uri "mongodb://ucfm@db1:27017/?authSource=admin" --target 7.0If you prefer, leave the password out of --uri and ucfm asks for it. For scripts, use the UCFM_URI environment variable or --uri-file.
The report starts with deployment-wide checks (upgrade path, FCV, health, sharding state), then one block per upgrade step. A shortened example:
The MongoDB deployment at db1:27017 (replica set rs0, 3 members), Percona
Server for MongoDB 6.0.29-23, will now be checked for compatibility issues for
upgrade to MongoDB 7.0 (path 6.0 → 7.0)...
================================================================================
Deployment-wide checks
================================================================================
1) Upgrade path (upgrade-path)
No issues found: from 6.0 (current) to 7.0 (target) is a supported upgrade
path.
2) Server versions across members (binary-versions-consistent)
No issues found: all 3 members run 6.0.29-23.
3) featureCompatibilityVersion (fcv-matches-binary)
No issues found: FCV is 6.0 on 3 members, the same as their binaries.
[...]
================================================================================
Upgrade 6.0 → 7.0
Checked against Percona Server for MongoDB 7.0, psmdb-7.0.45-24
================================================================================
[...]
20) PSMDB journal options (psmdb-journal-option-ignored)
Notice: storage.journal.enabled / --journal / --nojournal are set. PSMDB 7.0
and later always journal and ignore these settings, logging a startup
warning.
- db1:27017, db2:27017, db3:27017
Solution:
- Remove the journal settings from the configuration.
More information:
https://docs.percona.com/percona-server-for-mongodb/7.0/install/upgrade-from-60.html
[...]
24) Usage of removed commands (command-removed-in-use)
Warning: Clients ran these commands since the servers started (longest uptime
1d); 7.0 no longer implements them and will answer CommandNotFound.
- availableQueryOptions (6 calls)
Solution:
- Find the applications or tools issuing these commands (profiler, logs,
$currentOp) and update them before upgrading.
More information:
https://www.mongodb.com/docs/manual/release-notes/7.0-compatibility/
[...]
================================================================================
Errors: 0
Warnings: 3
Notices: 4
Checks with warnings:
- 24) Usage of removed commands (command-removed-in-use)
- 31) Floating-point rounding in $add (add-rounding)
- 35) $natural hint and sort values (natural-hint-values)
No errors were found. Review the 3 warnings before upgrading.Before going through the findings, read the top of the report: it tells you what is being checked, and the first checks tell you what could not be checked and how to fix that.
The tool checks one major upgrade at a time. When the target is further away, check 1 shows the full path and the report covers the next step only; run it again after each upgrade.
The exit code follows the result (0 clean, 1 warnings, 2 errors, 3 tool failure), so the check fits in a pipeline. Add --format json for machine-readable output, or --deep-check to sample documents for the changes that depend on stored data.
Upgrades are a good moment to look at the rest of the house. ucfm audit compares the deployment with the MongoDB Production Notes and Operations Checklist:
ucfm audit --uri "mongodb://ucfm@db1:27017/?authSource=admin"You can also append it to the ucfm check with --with-audit:
ucfm check --uri "mongodb://ucfm@db1:27017/?authSource=admin" --target 7.0 --with-auditOne run, one report with both sections.
With that, I believe you already have what you need for your next maintenance window. When you want to go further, like checking the operating system of each host or collecting a snapshot to analyze somewhere else, feel free to check the UCFM documentation, which holds more details.
UCFM was born of a desire to simplify a process and to answer the question highlighted at the beginning, a question that, until now, had no single command to answer.
Still, it does not replace your judgment, your backup, or the official upgrade procedure. It replaces the long manual checklist with a single read-only pass over the deployment you already have: one step at a time, with findings you can act on before the maintenance window.
Install it, point it at a node, pick a target, and read the report. Fix the errors, run it again, and let me know how it goes.
Suggestions, fixes, and features are all welcome; the project is open source at: github.com/jenunes/ucfm.
Resources
RELATED POSTS
