Upgrade the API version of your Azure Cosmos DB for MongoDB account

  • Article

APPLIES TO: MongoDB

This article describes how to upgrade the API version of your Azure Cosmos DB's API for MongoDB account. After your upgrade, you can use the latest functionality in Azure Cosmos DB's API for MongoDB. The upgrade process doesn't interrupt the availability of your account and it doesn't consume RU/s or decrease the capacity of the database at any point. This process doesn't affect existing data or indexes.

When upgrading to a new API version, start with development/test workloads before upgrading production workloads. It's important to upgrade your clients to a version compatible with the API version you're upgrading to before upgrading your Azure Cosmos DB for MongoDB account.

Warning

At this moment, only qualifying accounts using the server version 3.2 can be upgraded to version 3.6 and higher. If your account doesn't show the upgrade option, please file a support ticket.

Upgrade your version

  1. Sign into the Azure portal.

  2. Navigate to your Azure Cosmos DB for MongoDB account. Open the Overview pane and verify that your current Server version is either 3.2 or 3.6.

    Screenshot of how to check the current version of your MongoDB account from the Azure portal.

  3. From the left menu, open the Features pane. This pane shows the account level features that are available for your database account.

  4. Select the Upgrade MongoDB server version row. If you don't see this option, your account might not be eligible for this upgrade. File a support ticket if that is the case.

    Screenshot of the features page to0 upgrade your account.

  5. Review the information displayed about the upgrade. Select Set server version to 4.2 (or 4.0 or 3.6 depending upon your current version).

    Screenshot of upgrade guidance and the select upgrade option.

  6. After you start the upgrade, the Feature menu is greyed out, and the status is set to Pending. The upgrade takes around 15 minutes to complete. This process doesn't affect the existing functionality or operations of your database account. After it's complete, the Update MongoDB server version status will show the upgraded version. Contact support if there was an issue processing your request.

  7. The following are some considerations after upgrading your account:

    1. If you upgraded from 3.2, go back to the Overview pane, and copy the new connection string to use in your application. The old connection string running 3.2 isn't interrupted. To ensure a consistent experience, all your applications must use the new endpoint.

    2. If you upgraded from 3.6, your existing connection string is upgraded to the version specified and should continue to be used.

Downgrade your version

You can also downgrade your account to 4.0 or 3.6 via the same steps in the upgrade your version section.

  1. If you upgraded from 3.2 to and wish to downgrade back to 3.2, switch back to using your previous (3.2) connection string with the host accountname.documents.azure.cn, which remains active post-upgrade running version 3.2.

  2. Change the connection string in your application.

Related content