MongoDB releases new versions on a regular cadence. How you receive those versions and how much control you have over the timing depend on how you run MongoDB. Depending on your deployment type, you should prepare for running a new version in different ways.
This page explains what MongoDB version numbers mean, what the release types are, and how upgrades work in general terms. For the procedures and policies specific to your deployment, refer to the links throughout.
How MongoDB Versions Are Numbered
MongoDB version numbers take the form X.Y.Z:
X is the major version. A change here indicates a release that may include backward-incompatible changes and new features that persist data in formats earlier versions cannot read.
Y is the minor version. Minor releases deliver incremental features between major releases, and availability depends on your deployment type.
Z is the patch version. Patch releases contain fixes and are backward compatible within their release series.
Drivers, MongoDB Shell, and the MongoDB Database Tools version independently of the database server. A driver version number does not correspond to a server version number. To learn which driver versions work with which server versions, see the compatibility page for your driver.
Release Types
Major Releases
Major releases introduce new features and may include backward-incompatible changes. MongoDB supports major releases for both Atlas and self-managed deployments.
Minor Releases
Minor releases deliver features on a faster cadence between major releases.
Starting in MongoDB 8.2, minor releases are available to Atlas Auto Upgrade, Enterprise Advanced, and Community self-managed deployments. Starting in MongoDB 9.0, minor releases are available only through Atlas Auto Upgrade.
Note
Minor releases may not support every feature, notably Atlas Live Migration and mongosync.
Feature Update Releases
Starting in MongoDB 9.0, Feature Update releases are an annual minor release, numbered x.5, available to Atlas and self-managed deployments. Feature Update releases give Atlas Manual Upgrade and self-managed deployments a way to get incremental features without waiting for the next major version. They carry the same end-of-life timeline and Extended Lifecycle Support eligibility as the major version they extend.
Important
To receive all minor releases in MongoDB 9.0 and later, configure your Atlas cluster to Latest Version With Auto Upgrades. All other deployments are eligible only for the Feature Update release, not for other minor releases.
Patch Releases
Patch releases contain fixes and are backward compatible only within their own major and minor release series. You should always run the latest patch release for your major and minor version.
Release Candidates
Release candidates are pre-release builds intended for evaluating new features. They are not suitable for production deployments.
To learn more about how MongoDB numbers and schedules releases, see MongoDB Versioning.
How Releases Reach Your Deployment
MongoDB releases reach Atlas before they become available for self-managed deployments.
Important
An Atlas Auto Upgrade cluster configured to receive the latest versions may run a release before that release is available to download and install yourself.
What this means in practice depends on how you run MongoDB:
Atlas Manual Upgrade clusters stay on a major-version cadence that you control.
Atlas Auto Upgrade clusters receive new versions automatically as Atlas rolls them out.
Self-managed (Enterprise Advanced or Community) deployments let you choose when to download and install each release. Nothing changes until you act.
Feature Compatibility Version
Upgrading the MongoDB binaries and enabling the new version's features are two separate steps.
The feature compatibility version (FCV) controls whether features that write data in a format earlier versions cannot read are enabled. After you upgrade binaries, your deployment continues to run at the previous FCV until you raise it. This is deliberate, while FCV remains at the earlier version, you retain the ability to downgrade.
Note
On Atlas Auto Upgrade, Atlas automatically advances the FCV to match each new MongoDB version after an automated review of the rollout signals for the MongoDB binaries. You do not control the FCV.
Raising FCV is the point of no return. Once features that persist data in the new format are enabled, downgrading is not possible on Atlas.
For the command reference, see setFeatureCompatibilityVersion in the MongoDB Manual. For how FCV works on Atlas, including pinning FCV before an upgrade, see Upgrade Major MongoDB Version for a Cluster.
Support Lifecycle and End of Life
Each MongoDB major version is supported for five years, with an optional two-year Extended Lifecycle Support (ELS) period available to Enterprise Advanced customers. When a version reaches end of life, it no longer receives fixes, including security fixes, and MongoDB no longer maintains its documentation.
Handling differs by deployment type:
On Atlas, MongoDB notifies you of the version cut-off date before your version reaches end of life. After that date, Atlas upgrades your clusters to the current default target version for MongoDB.
Important
The current default target version for MongoDB is not always the immediately following major version.
Self-managed deployments require you to upgrade before the end of life.
To see which versions are currently supported on which platforms, see Supported Platforms for MongoDB Enterprise or Supported Platforms for MongoDB Community.
Choose Your Upgrade Path
If You Run | Version Cadence | Start Here |
|---|---|---|
Atlas Manual Upgrade | You choose when to move to the next major version. | |
Atlas Auto Upgrade | Atlas upgrades you automatically. Use maintenance waves to control the order across environments. | |
Enterprise Advanced | You choose when. | |
Community | You choose when. |
Self-Managed Upgrade Considerations
For self-managed deployments, upgrade procedures differ by topology. Each release's upgrade page links to standalone, replica set, and sharded cluster procedures.
In MongoDB versions before 9.0, you cannot skip minor releases when upgrading a self-managed deployment. To move between minor releases, you must upgrade through each one in sequence.
Starting in MongoDB 9.0, Enterprise Advanced deployments receive only the annual Feature Update release in addition to major releases. There is no longer a sequence of minors to skip within a release cycle.
Before You Upgrade
Whatever your deployment type, three things are worth doing before a major version upgrade:
Test your application against the new version before it reaches production.
How you accomplish this depends on your deployment:
Self-managed: upgrade a non-production deployment first.
Atlas Manual Upgrade: create a staging cluster running the target version and test against it. See Upgrade Major MongoDB Version for a Cluster.
Atlas Auto Upgrade: you can use maintenance waves to sequence staging and production environments, but they may not stop the rollout and do not give you full control over upgrade timing.
Important
If you need more time to validate a release, use a major-version cadence instead. To learn more about maintenance waves, see Manage Cluster Maintenance.
Downgrades
Downgrading is constrained, and the constraints differ by deployment type. Select your deployment type to see the constraints that apply to you.
Downgrading requires that FCV was not raised, or was pinned before the original upgrade.
A cluster can downgrade only to the immediately preceding release, either the previous major version or that major version's Feature Update release, and downgrades cannot be chained across multiple versions.
A cluster on a Feature Update release can downgrade to its own major version.
With very few exceptions, a downgrade lands on the latest patch release of the target version.
After a downgrade, features introduced in the newer version are no longer available, and MongoDB does not support a second downgrade from the new, lower position.
You cannot downgrade clusters.
Note
To move to a major-version cadence eligible for downgrades, switch as a self-service action after the major version release (
x.0.0) and before the first minor release in that cycle (x.1.0). To learn more, see Latest Version With Auto Upgrades.
- Downgrades are supported only between adjacent versions and require procedures specific to your cluster configuration.
Downgrading requires that FCV was not raised, or was pinned before the original upgrade.
A cluster can downgrade only to the immediately preceding release, either the previous major version or that major version's Feature Update release, and downgrades cannot be chained across multiple versions.
A cluster on a Feature Update release can downgrade to its own major version.
With very few exceptions, a downgrade lands on the latest patch release of the target version.
After a downgrade, features introduced in the newer version are no longer available, and MongoDB does not support a second downgrade from the new, lower position.
Learn More
MongoDB Versioning for release numbering and cadence in detail
Release Notes for per-version release notes, compatibility changes, and upgrade and downgrade procedures
MongoDB Versions in Atlas to see Atlas release cadence options