You can upgrade the major version of your Atlas cluster at any time by modifying the cluster.
To ensure that your transition to the new MongoDB version is smooth and doesn't affect your application, before you upgrade the major version on your production Atlas cluster, use the following procedure to create a staging cluster and test your application against the new MongoDB version.
The following considerations apply:
Your cluster must be in a healthy state before upgrading.
If you take an on-demand snapshot before a major version upgrade, wait until the snapshot completes before you upgrade the version.
You can only upgrade your Atlas cluster one major version at a time. You cannot skip any major versions when upgrading your cluster.
Each major version contains some features which may not be backward-compatible with previous versions. When upgrading to a new major version, check the Release Notes for changes which may affect your applications. Alternatively, if you use the Stable API, you ensure that behavior changes between MongoDB versions do not break your application after an upgrade.
The MongoDB Stable API encompasses a subset of MongoDB commands that applications use to read and write data, create collections and indexes, and perform other common tasks. The Stable API allows you to specify which version of the MongoDB API your application runs against and provides long-term API stability for applications. It supports more frequent releases and automatic server upgrades, allowing your applications to take advantage of rapidly released features without risking backward incompatible changes.
After upgrading the MongoDB major version, you will not be able to downgrade to previous versions unless you pinned the cluster's FCV before upgrading.
Live migration requires the FCVs on the source and destination clusters to match their major versions. To learn more about supported migration paths, see Migrate or Import Data.
Starting with MongoDB 6.0, the $$SEARCH_META aggregation variable can't be used in any subsequent stage after a $searchMeta stage.
If you want to upgrade to MongoDB 6.0 from a previous version and use the $$SEARCH_META aggregation variable in your Atlas Search $searchMeta queries, review them before you upgrade your cluster to avoid errors.
To upgrade a cluster, you must have the Project Owner or higher role for the project.
To upgrade your major MongoDB version:
WARNING: Navigation Improvements In Progress We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If it's not already displayed, click Clusters in the sidebar.
The Clusters page displays.
You can skip this step if you already have an Atlas cluster as your staging environment.
Click the Create button to open the cluster creation modal. Configure the staging cluster to match your production cluster. You do not have to enable backups for the staging cluster.
To learn how to create a new cluster, see Create a Cluster.
ImportantIf selecting a smaller cluster tier for the staging cluster, take into consideration that any performance tests run may not be representative of the performance of the upgraded production cluster. You may also need to select a larger storage size depending on the amount of data you want to mirror to your staging cluster.
NoteYou can skip this step if you already have an up-to-date Atlas cluster as a staging environment.
If you have backups enabled for the production cluster, restore the most recent snapshot and choose the staging cluster as the destination.
If you do not have backups enabled for the production cluster, use Atlas Live Import to mirror data from your production cluster to the staging cluster. The live migration documentation includes specific instructions for creating staging environments.
Update your staging application to point at your staging cluster. For instructions on retrieving the MongoDB driver-friendly connection string for the staging cluster, see Connect via Drivers.
Confirm that your application can connect successfully to the staging cluster and that the application operates as expected.
Upgrading your application to the latest MongoDB drivers for your cluster's MongoDB version enables full access to the features provided by the newer MongoDB version. You may also find better performance or stability with newer driver versions. See Connect via Drivers for documentation on the recommended MongoDB driver for a given MongoDB version and connection examples. By using the Stable API, you can ensure that behavior changes between MongoDB versions do not break your application.
If you encounter a bug after upgrading your application, file a ticket in the JIRA project for your MongoDB driver.
WARNING: Navigation Improvements In Progress We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If it's not already displayed, click Clusters in the sidebar.
The Clusters page displays.
Click Edit Config and select your staging cluster from the drop-down menu.
Change the cluster version to the desired major MongoDB Version.
ImportantYou can't downgrade the MongoDB version of a Atlas cluster unless the cluster's FCV was previously pinned before upgrading. If you want to redeploy the staging environment with the original MongoDB version, you must terminate and re-create the cluster.
Click Confirm & Deploy to deploy your changes.
Atlas automatically begins upgrading the cluster. Consider measuring the time required by Atlas to upgrade the cluster to set a general expectation for your production cluster upgrade.
File a support ticket if you encounter version-specific issues with the upgraded staging cluster.
Perform any required performance and operational testing of the staging cluster.
File a support ticket if you encounter version-specific issues with the upgraded staging cluster.
ImportantThe major version upgrade requires at least one replica set election. Use the staging cluster as an opportunity to test your application's resilience to primary failover. See Test Primary Failover for complete documentation.
Once you are confident in the performance and operation of your staging cluster, repeating the upgrade procedure for your production cluster.
Once Atlas completes the upgrade process, check that your production applications are still connected and operating normally.
If you upgraded your staging application with newer MongoDB drivers and are satisfied with the performance and operation, consider scheduling a maintenance period for upgrading your production applications.
If you encounter problems with the upgraded production cluster, file a High Priority support ticket using the procedure in the following section.
MongoDB major version upgrades are supported by both Atlas and on-premises deployments. The FCV enables or disables features that persist data incompatible with earlier versions of MongoDB. You can pin a cluster's FCV before upgrading in Atlas, which enables you to revert MongoDB to the previous version after upgrading without experiencing version compatibility issues.
The following procedures allow you to pin and unpin FCV for your cluster, downgrade your cluster by one major version, or file a support ticket.
WarningThe FCV is a short-term measure that only persists for up to 4 weeks after the pin date, and doesn't simulate the behavior of the previous binary versions. It only postpones upgrading certain internal data structures that allow new server features. After you are confident that a downgrade to the previous version is unnecessary, unpin the FCV to match the current binary version.
FCV pinning is only available on Dedicated clusters.
FCV pin can't be extended beyond 4 weeks from the pin date.
FCV pinning is not supported for clusters on rapid release.
You can't upgrade to a version that is 2 versions above the pinned FCV version. If a cluster is pinned to FCV 6.0, you can only upgrade to 7.0, not 8.0+.
You should pin a cluster's FCV before the cluster's version reaches end-of-life.
When your cluster has a pinned FCV, a pin icon appears next to your cluster's Version at the bottom of the cluster card. If you hover your cursor over the pin icon, a tooltip that shows the FCV and the expiration date appears.
Atlas unpins your cluster's FCV on the next maintenance window starting on or after the expiration date.
If you already upgraded your cluster's MongoDB version, Atlas upgrades its FCV to match its MongoDB version after the pin expires.
To pin the FCV for your cluster:
WARNING: Navigation Improvements In Progress We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If it's not already displayed, click Clusters in the sidebar.
The Clusters page displays.
A modal appears with the Feature Compatibility Version and the Set expiration date field.
All dates are set to Timestamp in ISO 8601 date and time format in UTC, in the MM/DD/YYYY format. Set the FCV expiration date to be within four weeks of the date to which you pinned the FCV. When the expiration date passes, the tooltip displays Expired XX/XX/XXXX. Your FCV pin automatically expires after 4 weeks.
After the FCV pin expires, Atlas unpins your cluster's FCV on the next maintenance window starting on or after the expiration date. If you already upgraded your cluster's MongoDB version, Atlas upgrades its FCV to match its MongoDB version.
To unpin the FCV for your cluster:
WARNING: Navigation Improvements In Progress We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If it's not already displayed, click Clusters in the sidebar.
The Clusters page displays.
A modal appears with the Feature Compatibility Version and the Edit expiration date field.
The following limitations apply to downgrading your cluster's version:
You can only downgrade if you pin the cluster's FCV before upgrading.
You can only downgrade your cluster to the major version that matches the pinned FCV.
You can only perform this action if the pinned FCV is only one major version below the current FCV and you don't have rapid release enabled.
You can't downgrade to a version after it reaches end-of-life.
To downgrade your cluster by one major version:
WARNING: Navigation Improvements In Progress We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If it's not already displayed, click Clusters in the sidebar.
The Clusters page displays.
A warning banner appears indicating that your cluster's MongoDB version will be downgraded.
If you have any questions regarding migration support beyond what is covered in this documentation, or if you encounter an error during migration, file a support ticket through the Atlas user interface.
If you have any questions or need further assistance, reach out to our support team.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4