|
1 | 1 | --- |
2 | | -title: Upgrade the Mongo version of your Azure Cosmos DB's API for MongoDB account |
| 2 | +title: Upgrade the Mongo version |
| 3 | +titleSuffix: Azure Cosmos DB for MongoDB |
3 | 4 | description: How to upgrade the MongoDB wire-protocol version for your existing Azure Cosmos DB's API for MongoDB accounts seamlessly |
| 5 | +author: gahl-levy |
| 6 | +ms.author: gahllevy |
4 | 7 | ms.service: cosmos-db |
5 | 8 | ms.subservice: mongodb |
6 | 9 | ms.topic: how-to |
7 | | -ms.date: 02/23/2022 |
8 | | -author: gahl-levy |
9 | | -ms.author: gahllevy |
| 10 | +ms.date: 06/06/2024 |
| 11 | +#Customer Intent: As a developer, I want to change my MongoDB version, so that I can use the features I need in my applications. |
10 | 12 | --- |
11 | 13 |
|
12 | 14 | # Upgrade the API version of your Azure Cosmos DB for MongoDB account |
| 15 | + |
13 | 16 | [!INCLUDE[MongoDB](~/reusable-content/ce-skilling/azure/includes/cosmos-db/includes/appliesto-mongodb.md)] |
14 | 17 |
|
15 | | -This article describes how to upgrade the API version of your Azure Cosmos DB's API for MongoDB account. After you 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. No existing data or indexes will be affected by this process. |
| 18 | +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. |
16 | 19 |
|
17 | | -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 are upgrading to before upgrading your Azure Cosmos DB for MongoDB account. |
| 20 | +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. |
18 | 21 |
|
19 | | ->[!Note] |
| 22 | +> [!WARNING] |
20 | 23 | > 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](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade). |
21 | 24 |
|
22 | | -## Upgrading to 4.2, 4.0, or 3.6 |
23 | | -### Benefits of upgrading to version 4.2: |
24 | | -- Several major improvements to the aggregation pipeline such as support for `$merge`, Trigonometry, arithmetic expressions, and more. |
25 | | -- Support for client side field encyption which further secures your database by enabling individual fields to be selectively encrypted and maintaining privacy of the encrypted data from database users and hosting providers. |
26 | | - |
27 | | - |
28 | | - |
29 | | -### Benefits of upgrading to version 4.0 |
30 | | - |
31 | | -The following are the new features included in version 4.0: |
32 | | -- Support for multi-document transactions within unsharded collections. |
33 | | -- New aggregation operators |
34 | | -- Enhanced scan performance |
35 | | -- Faster, more efficient storage |
36 | | - |
37 | | -### Benefits of upgrading to version 3.6 |
38 | | - |
39 | | -The following are the new features included in version 3.6: |
40 | | -- Enhanced performance and stability |
41 | | -- Support for new database commands |
42 | | -- Support for aggregation pipeline by default and new aggregation stages |
43 | | -- Support for Change Streams |
44 | | -- Support for compound Indexes |
45 | | -- Cross-partition support for the following operations: update, delete, count and sort |
46 | | -- Improved performance for the following aggregate operations: $count, $skip, $limit and $group |
47 | | -- Wildcard indexing is now supported |
48 | | - |
49 | | -### Changes from version 3.2 |
50 | | - |
51 | | -- By default, the [Server Side Retry (SSR)](prevent-rate-limiting-errors.md) feature is enabled, so that requests from the client application will not return 16500 errors. Instead requests will resume until they complete or hit the 60 second timeout. |
52 | | -- Per request timeout is set to 60 seconds. |
53 | | -- MongoDB collections created on the new wire protocol version will only have the `_id` property indexed by default. |
54 | | - |
55 | | -### Action required when upgrading from 3.2 |
56 | | - |
57 | | -When upgrading from 3.2, the database account endpoint suffix will be updated to the following format: |
58 | | - |
59 | | -``` |
60 | | -<your_database_account_name>.mongo.cosmos.azure.com |
61 | | -``` |
62 | | - |
63 | | -If you are upgrading from version 3.2, you will need to replace the existing endpoint in your applications and drivers that connect with this database account. **Only connections that are using the new endpoint will have access to the features in the new API version**. The previous 3.2 endpoint should have the suffix `.documents.azure.com`. |
64 | | - |
65 | | -When upgrading from 3.2 to newer versions, [compound indexes](indexing.md) are now required to perform sort operations on multiple fields to ensure stable, high performance for these queries. Ensure that these compound indexes are created so that your multi-field sorts succeed. |
66 | | - |
67 | | ->[!Note] |
68 | | -> This endpoint might have slight differences if your account was created in a Sovereign, Government or Restricted Azure Cloud. |
69 | | -
|
70 | | -## How to upgrade |
| 25 | +## Upgrade your version |
71 | 26 |
|
72 | 27 | 1. Sign into the [Azure portal.](https://portal.azure.com/) |
73 | 28 |
|
74 | 29 | 1. 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. |
75 | 30 |
|
76 | | - :::image type="content" source="media/upgrade-version/check-current-version.png" alt-text="Check the current version of your MongoDB account from the Azure portal." border="true"::: |
| 31 | + :::image type="content" source="media/upgrade-version/check-current-version.png" alt-text="Screenshot of how to check the current version of your MongoDB account from the Azure portal."::: |
77 | 32 |
|
78 | 33 | 1. From the left menu, open the `Features` pane. This pane shows the account level features that are available for your database account. |
79 | 34 |
|
80 | | -1. Select the `Upgrade MongoDB server version` row. If you don't see this option, your account might not be eligible for this upgrade. Please file [a support ticket](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade) if that is the case. |
| 35 | +1. 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](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade) if that is the case. |
81 | 36 |
|
82 | | - :::image type="content" source="media/upgrade-version/upgrade-server-version.png" alt-text="Open the Features blade and upgrade your account." border="true"::: |
| 37 | + :::image type="content" source="media/upgrade-version/upgrade-server-version.png" alt-text="Screenshot of the features page to0 upgrade your account."::: |
83 | 38 |
|
84 | 39 | 1. 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). |
85 | 40 |
|
86 | | - :::image type="content" source="media/upgrade-version/select-upgrade.png" alt-text="Review upgrade guidance and select upgrade." border="true"::: |
| 41 | + :::image type="content" source="media/upgrade-version/select-upgrade.png" alt-text="Screenshot of upgrade guidance and the select upgrade option."::: |
87 | 42 |
|
88 | | -1. 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 will not 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. Please [contact support](https://azure.microsoft.com/support/create-ticket/) if there was an issue processing your request. |
| 43 | +1. 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](https://azure.microsoft.com/support/create-ticket/) if there was an issue processing your request. |
89 | 44 |
|
90 | 45 | 1. The following are some considerations after upgrading your account: |
91 | 46 |
|
92 | | - 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 will not be interrupted. To ensure a consistent experience, all your applications must use the new endpoint. |
| 47 | + 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. |
| 48 | + |
| 49 | + 1. If you upgraded from 3.6, your existing connection string is upgraded to the version specified and should continue to be used. |
| 50 | + |
| 51 | +> [!IMPORTANT] |
| 52 | +> When upgrading from 3.2, the database account endpoint suffix will be updated to the following format: `<your_database_account_name>.mongo.cosmos.azure.com`. This endpoint may have slight differences if your account was created in a Sovereign, Government or Restricted Azure Cloud. |
| 53 | +> |
| 54 | +> If you are upgrading from version 3.2, you will need to replace the existing endpoint in your applications and drivers that connect with this database account. **Only connections that are using the new endpoint will have access to the features in the new API version**. The previous 3.2 endpoint should have the suffix `.documents.azure.com`. |
| 55 | +> When upgrading from 3.2 to newer versions, [compound indexes](indexing.md) are now required to perform sort operations on multiple fields to ensure stable, high performance for these queries. Ensure that these compound indexes are created so that your multi-field sorts succeed. |
93 | 56 |
|
94 | | - 1. If you upgraded from 3.6, your existing connection string will be upgraded to the version specified and should continue to be used. |
| 57 | +## Downgrade your version |
95 | 58 |
|
96 | | -## How to downgrade |
| 59 | +You can also downgrade your account to 4.0 or 3.6 via the same steps in the [upgrade your version](#upgrade-your-version) section. |
97 | 60 |
|
98 | | -You may also downgrade your account to 4.0 or 3.6 via the same steps in the 'How to Upgrade' section. |
| 61 | +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.com`, which remains active post-upgrade running version 3.2. |
99 | 62 |
|
100 | | -If you upgraded from 3.2 to and wish to downgrade back to 3.2, you can simply switch back to using your previous (3.2) connection string with the host `accountname.documents.azure.com` which remains active post-upgrade running version 3.2. |
| 63 | +1. Change the connection string in your application. |
101 | 64 |
|
102 | | -## Next steps |
| 65 | +## Related content |
103 | 66 |
|
104 | | -- Learn about the supported and unsupported [features of MongoDB version 4.2](feature-support-42.md). |
105 | | -- Learn about the supported and unsupported [features of MongoDB version 4.0](feature-support-40.md). |
106 | | -- Learn about the supported and unsupported [features of MongoDB version 3.6](feature-support-36.md). |
107 | | -- For further information check [Mongo 3.6 version features](https://devblogs.microsoft.com/cosmosdb/azure-cosmos-dbs-api-for-mongodb-now-supports-server-version-3-6/) |
108 | | -- Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning. |
109 | | - - If all you know is the number of vcores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md) |
110 | | - - If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-capacity-planner.md) |
| 67 | +- [MongoDB version 6.0 features](feature-support-60.md) |
| 68 | +- [MongoDB version 5.0 features](feature-support-50.md) |
| 69 | +- [MongoDB version 4.2 features](feature-support-42.md) |
| 70 | +- [MongoDB version 4.0 features](feature-support-40.md) |
| 71 | +- [MongoDB version 3.6 features](feature-support-36.md) |
| 72 | +- [MongoDB version history](https://www.mongodb.com/resources/products/mongodb-version-history) |
0 commit comments