Rolling upgrades and featureCompatibilityVersion
Upgrade replica sets and sharded clusters without downtime, use FCV as the safety latch, and plan the rollback path.
- Perform a rolling upgrade of a replica set
- Order a sharded cluster upgrade
- Explain what FCV controls and when to raise it
- Prepare a rollback plan and driver compatibility checks
conceptThe concept
- Read the release notes and compatibility changes; check driver versions; test in staging with production-like data and traffic.
- Upgrade one major version at a time (6.0 → 7.0 → 8.0). FCV must equal the current version before the next upgrade.
- Replica set: upgrade secondaries one at a time (shutdown, replace binaries, start, wait until SECONDARY and caught up), then
rs.stepDown()the primary and upgrade it. - Sharded cluster: stop the balancer, upgrade config server replica set, then each shard (rolling), then mongos instances, then re-enable the balancer.
- Run on the new binaries for a while with the old FCV. When confident,
setFeatureCompatibilityVersionto the new version (7.0+ requiresconfirm: true).
The featureCompatibilityVersion controls which features that change on-disk formats or protocols are enabled. While FCV is old, you can still downgrade binaries; after raising it, downgrading needs lowering FCV first (and some versions only support downgrade through support-assisted procedures).
whyWhy it matters
Running unsupported versions accumulates risk (no security fixes); botched upgrades cause outages. FCV gives you a window to validate the new binaries in production with an easy way back.
Use caseReal-world scenario
Upgrading a 3-shard cluster from 7.0 to 8.0: binaries rolled out over two maintenance windows with the balancer stopped, two weeks of observation at FCV 7.0 (comparing latency dashboards and slow query rates), then FCV raised to 8.0 in a low-traffic window, with the rollback runbook rehearsed in staging.
Try itExamples
Run and edit these in the interactive lesson.
db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
db.adminCommand({ setFeatureCompatibilityVersion: "8.0", confirm: true })
db.version()# 1. confirm health and lag
mongosh --eval 'rs.status().members.map(m => [m.name, m.stateStr, m.optimeDate])'
# 2. clean shutdown
mongosh admin --eval 'db.shutdownServer()'
# 3. install new binaries / change container image
sudo apt-get install -y mongodb-org=8.0.4
# 4. start and wait for SECONDARY + caught up, then move to the next member
sudo systemctl start mongod
# 5. finally on the primary
mongosh --eval 'rs.stepDown(120)' # then upgrade it like a secondary
# 6. after the soak period
mongosh admin --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "8.0", confirm: true })'internalsUnder the hood
Raising FCV can trigger metadata conversions (for example, on-disk format or catalog changes) and is itself replicated. In sharded clusters it is coordinated by the config server. Mixed-version replica sets are supported only during the upgrade window. Operator-managed Kubernetes deployments perform the same sequence through the custom resource (image version, then FCV field).
Avoid / preferDo this, not that
# 6.0 -> 8.0 binaries in one jump
# 6.0 -> 7.0, then setFeatureCompatibilityVersion "7.0" # 7.0 -> 8.0, then setFeatureCompatibilityVersion "8.0"
In-place upgrades go one major release at a time, and each step needs the FCV raised before the next binary.
db.adminCommand({ setFeatureCompatibilityVersion: "8.0", confirm: true })
// minutes after the binary upgrade// run the new binaries at the old FCV for days of normal traffic, // then raise FCV once you are sure you will not roll back
While FCV stays at the old version you can still downgrade binaries. Raising it enables new on-disk features and makes rollback much harder.
PitfallsCommon mistakes
- Raising FCV immediately after upgrading binaries, removing the easy rollback path.
- Skipping a major version.
- Leaving the balancer running during a sharded cluster upgrade.
- Not checking driver compatibility (old drivers may not support new wire versions).
- Upgrading all members simultaneously.
LimitsWhen not to use it
Do not leave a cluster on mixed binary versions for long; it is a transition state. Do not upgrade the server before checking that every driver in use supports the new version.
SecuritySecurity notes
Staying on supported versions is a security control: end-of-life releases get no fixes for new vulnerabilities. Plan upgrades well before end of life, and verify package signatures when installing binaries.
ChallengeTry it yourself
Report the binary version, the featureCompatibilityVersion and whether the FCV matches the binary's major version.
Show one solution
const fcv = db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 }).featureCompatibilityVersion.version
const bin = db.version()
printjson({ binary: bin, fcv, fcvMatchesBinary: bin.startsWith(fcv) })InterviewQuestions you should be able to answer
What is FCV and why does it exist?
featureCompatibilityVersion gates features that are not backward compatible (data formats, internal protocols). New binaries run with the old FCV, so the deployment behaves compatibly and binaries can be downgraded. Once validated, raising FCV enables the new features. To downgrade binaries later you must first lower FCV, if the version supports it.
Describe the order of a sharded cluster upgrade.
Stop the balancer, upgrade the config server replica set (rolling: secondaries, step down, primary), upgrade each shard replica set the same way, upgrade mongos routers, restart the balancer, soak, then raise FCV via mongos.
QuizCheck your understanding
4 questions with instant feedback in the interactive lesson; a wrong answer goes into your review deck.