Skip to the stories
AI & ML

UCFM Checks MongoDB Upgrade Readiness Across Each Major Version Step

  • Jean da Silva
  • 432 reads

UCFM scans MongoDB deployments for upgrade risks, configuration issues and behavior changes, then reports what to address before maintenance.

UCFM Checks MongoDB Upgrade Readiness Across Each Major Version Step

MongoDB upgrades are difficult because the binary change is only one part of the work. Teams also need to check configuration, application behavior, stored data and cluster health against each release in the upgrade path. UCFM, an open source read only checker for MongoDB and Percona Server for MongoDB, brings many of those checks into one report before the maintenance window.

One report for each upgrade step

MongoDB major upgrades proceed one release at a time. A move from 6.0 to 8.0, for example, requires separate upgrades from 6.0 to 7.0 and from 7.0 to 8.0, with a binary change and a featureCompatibilityVersion (FCV) change at each step. Preparation therefore needs to account for the changes in every intermediate release.

That work can span several parts of a deployment. Administrators need to review compatibility notes and release notes, inspect configuration files and setParameter values, and look for removed commands, operators or aggregation stages in applications, views and custom roles. On a sharded cluster, the same investigation extends across config servers, shards and related components.

UCFM is designed to make that review more systematic. Its approach draws on MySQL Shell’s upgrade checker, util.checkForServerUpgrade(): checks are numbered, findings are classified as errors, warnings or notices, and the report identifies affected objects and relevant documentation. The practical benefit is a consolidated view of issues to address, rather than a checklist assembled manually from separate release pages.

What UCFM checks

The tool connects to one node and discovers reachable members of a replica set or, for a sharded deployment, the config servers, shards and mongos routers. It reads deployment facts and checks three broad areas: features removed between versions, changes described in release notes, and behavior changes that may affect the deployment.

UCFM does not perform the upgrade. It reports what it can observe and suggests actions, leaving the upgrade procedure and decisions with the operator. The results can still help answer the key planning question: what appears likely to break, and where should remediation start?

Installation and access

The installation command downloads the latest release, checks its checksum and places the executable in /usr/local/bin, or in ~/.local/bin when run without root access. Running the same command later installs an update:

curl -fsSL https://raw.githubusercontent.com/jenunes/ucfm/main/install.sh | bash

For its checks, UCFM needs read access to cluster monitoring data, databases, users, roles and view definitions. The setup uses MongoDB’s clusterMonitor and readAnyDatabase roles plus a custom ucfmViewSecurity role. The latter grants the required access to user and role metadata and to the system.views collection; it can be removed after use if desired.

On a sharded cluster, create the user through a mongos and on the primary of each shard. UCFM connects to shard members directly, which means those members also need a shard local user. If one is missing, the tool identifies the affected shard.

Running a readiness check

To start a check, provide a connection URI and the target major version. The URI can point to any replica set member or to a mongos router:

ucfm check --uri "mongodb://ucfm@db1:27017/?authSource=admin" --target 7.0

Leave the password out of the URI to be prompted for it. For automated runs, the connection can instead come from the UCFM_URI environment variable or a file passed with --uri-file.

The report begins with deployment wide checks covering the upgrade path, FCV, health and sharding state, then gives a section for the next major version step. In an example check from Percona Server for MongoDB 6.0.29-23 to 7.0, it flags two concrete issues. A notice identifies journal settings that Percona Server for MongoDB 7.0 and later ignore, recommending their removal from configuration. A warning reports observed use of the removed availableQueryOptions command and advises finding the applications or tools that issue it before upgrading.

Each finding includes the hosts or objects involved, a suggested action and, where available, a documentation link. At the end, counts summarize errors, warnings and notices. The sample report has no errors but asks operators to review three warnings before proceeding.

Automation and deeper checks

UCFM checks one major version transition per run. If the requested target is several releases away, the report shows the full supported path but assesses only the next step. Operators run the check again after each upgrade, which keeps findings tied to the version transition currently being planned.

Exit codes make the result usable in scripts and pipelines: 0 means no findings requiring attention, 1 indicates warnings, 2 indicates errors, and 3 signals a tool failure. Use --format json for machine readable output. The --deep-check option samples documents for checks that depend on the data stored in the deployment, expanding coverage beyond configuration and observed server activity.

There is also an audit mode for production settings. ucfm audit compares a deployment with MongoDB’s Production Notes and Operations Checklist; --with-audit adds those results to an upgrade check in the same report. The UCFM documentation describes further options, including checks of host operating systems and collecting a snapshot for separate analysis.

What the report can and cannot establish

A read only scan can make upgrade preparation faster and expose issues that might otherwise be missed across multiple release steps. Its findings depend on the information it can reach and, for some checks, on activity observed since the servers started or on sampled documents. A clean report should therefore be read within those limits.

UCFM complements the operator’s judgment, backups and the prescribed upgrade procedure. Its most useful role is as an actionable preflight: run it against the deployment, resolve findings that apply, and repeat the check before each major version transition. The project is available at github.com/jenunes/ucfm.

Source: Jean da Silva · www.percona.com

From the same set