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 clusters on Auto Upgrades. They are also available to Enterprise Advanced and Community self-managed deployments.
Starting in MongoDB 9.0:
Minor releases are available to Atlas clusters on Auto Upgrades.
Minor releases are not available to Atlas clusters on Manual Upgrades or to self-managed deployments.
For incremental feature releases, see Feature Update Releases.
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. Atlas clusters on Manual Upgrades and self-managed deployments can use Feature Update releases to get incremental features without waiting for the next major version.
Feature Update releases 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.
Note
Free and Flex clusters stay on a major version. You can't choose a release cadence, and Atlas upgrades them automatically.
Atlas uses two distinct methods to deliver upgrades to your deployments: Manual Upgrades in Atlas and Auto Upgrades in Atlas.
Manual Upgrades in Atlas: You control when to upgrade to a new major version.
- Atlas Core clusters: You can choose a specific major version and control when you upgrade to it.
Auto Upgrades in Atlas: Atlas delivers new releases automatically.
Atlas Infinite clusters: Atlas Infinite clusters always use Auto Upgrades. For Atlas Infinite clusters, the option Latest Version With Auto Upgrades in the Atlas UI is always enabled.
Atlas Core clusters: Atlas Core clusters can use Auto Upgrades. To enable this behavior, select the option Latest Version With Auto Upgrades in the Atlas UI.
Important
An Atlas cluster on Auto Upgrades might run a release before that release is available to download and install yourself on self-managed deployments.
For Manual Upgrades for Self-managed Deployments (Enterprise Advanced or Community), 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
For Atlas clusters on Auto Upgrades, Atlas advances the FCV to match each new major MongoDB version. Atlas first runs 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 sends an email notification at least six months before the version reaches end of life. The notification includes instructions to upgrade your clusters yourself. A few months after the notification, Atlas stops allowing new deployments on that version. If you haven't upgraded by the date stated in the notification, Atlas upgrades your existing clusters to the current default target version for MongoDB. Atlas performs the upgrade during your configured maintenance window if you have one.
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 |
|---|---|---|
Manual Upgrades in Atlas | You choose when to move to the next major version. | |
Auto Upgrades in Atlas | Atlas upgrades you automatically. Use maintenance waves to control the order across environments. | |
Upgrades in Self-Managed Deployments (Enterprise Advanced and 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
Before you upgrade a major version of MongoDB, we recommend that you take the following actions, regardless of the upgrade type you choose:
Test your application against the new version before it reaches production.
How you perform these actions depends on your deployment.
Self-managed: upgrade a non-production deployment first.
Manual Upgrades in Atlas: create a staging cluster running the target version and test against it. See Upgrade Major MongoDB Version for a Cluster.
Auto Upgrades in Atlas: use maintenance waves to upgrade staging and production environments sequentially. Maintenance waves may not stop the rollout and do not give you full control over upgrade timing. For Atlas Core clusters, you can switch to Manual Upgrades if you require more time to validate a release. To learn more about maintenance waves, see Manage Cluster Maintenance.
Downgrades
Downgrading is constrained, and the constraints depend on your deployment. Select the option that matches your deployment 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.
Downgrades are only supported 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.
You cannot downgrade any Atlas cluster that uses Auto Upgrades. In particular:
You cannot downgrade Atlas Infinite clusters because they always use Auto Upgrades.
You cannot downgrade Atlas Core clusters that use Auto Upgrades. To downgrade an Atlas Core cluster, you need to first switch the cluster to Manual Upgrades and do it after the major version release (
x.0.0) and before the first minor release in that cycle (x.1.0). To learn more, see Auto Upgrades in Atlas.
Note
You cannot downgrade Free and Flex clusters.
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
MongoDB Atlas Core: Overview and MongoDB Atlas Infinite: Overview to learn about the Atlas database editions