All Products
Search

This Product

    ApsaraDB for MongoDB:Notes on major MongoDB database version upgrades

    Document Center

    ApsaraDB for MongoDB:Notes on major MongoDB database version upgrades

    Last Updated:Jun 04, 2026

    ApsaraDB for MongoDB supports upgrading the major version of your database. Before upgrading, determine which major versions your instance can upgrade to based on its service architecture and current version, and review compatibility changes between major versions.

    Supported upgrade paths

    • You can upgrade the major version of an instance directly in the ApsaraDB for MongoDB console. Available target versions depend on the instance's architecture, edition, and current version. The following tables describe the supported upgrade paths.

      Architecture

      Instance edition

      Current major version

      Available target major version

      standalone architecture

      General-purpose with cloud disk

      MongoDB 4.0

      No higher major version is available.

      General-purpose with cloud disk

      MongoDB 3.4

      Major version upgrade is not supported.

      To upgrade the major version, you can create a new instance and use it to replace the current instance.

      replica set architecture

      • General-purpose with cloud disk

      • Dedicated with cloud disk

      MongoDB 8.0

      No higher major version is available.

      MongoDB 7.0

      MongoDB 8.0

      MongoDB 6.0

      MongoDB 7.0

      MongoDB 5.0

      MongoDB 6.0

      MongoDB 4.4

      MongoDB 5.0

      After an upgrade from version 4.4 to 5.0, the default write concern changes from {w:1} to {w:majority}. This change may cause a degradation in write performance and an increase in write latency. Before you proceed with the upgrade, make sure that you understand the impact of this change.

      • General-purpose with local disk

      • Dedicated with local disk

      • Dedicated Physical Server

      MongoDB 4.2

      Major version upgrade is not supported.

      To upgrade the major version, you can create a new instance and use it to replace the current instance.

      MongoDB 4.0

      MongoDB 4.2

      MongoDB 3.4

      • MongoDB 4.0

      • MongoDB 4.2

      MongoDB 3.2

      MongoDB 3.0

      sharded cluster architecture

      Dedicated with cloud disk

      MongoDB 8.0

      No higher major version is available.

      MongoDB 7.0

      MongoDB 8.0

      MongoDB 6.0

      MongoDB 7.0

      MongoDB 5.0

      MongoDB 6.0

      MongoDB 4.4

      MongoDB 5.0

      After an upgrade from version 4.4 to 5.0, the default write concern changes from {w:1} to {w:majority}. This change may cause a degradation in write performance and an increase in write latency. Before you proceed with the upgrade, make sure that you understand the impact of this change.

      • General-purpose with local disk

      • Dedicated with local disk

      • Dedicated Physical Server

      MongoDB 4.2

      Major version upgrade is not supported.

      To upgrade the major version, you can create a new instance and use it to replace the current instance.

      MongoDB 4.0

      MongoDB 4.2

      MongoDB 3.4

      • MongoDB 4.0

      • MongoDB 4.2

      MongoDB 3.2

      MongoDB 3.0

    • To upgrade across different architectures or storage types, first create an instance with the target major version, and then use Data Transmission Service (DTS) to migrate data from the source instance to the new instance.

      The following topics describe how to migrate data:

    Compatibility changes between major versions

    Compatibility changes between major database versions are as follows:

    Important

    • The instance must be Running to upgrade its major database version. For instructions, see Upgrade database version.

    • Downgrading after a major version upgrade is not supported.

    • MongoDB 4.0 and later are compatible with MongoDB 3.6 features. To use MongoDB 3.6 features, upgrade to MongoDB 4.0 or later.

    • These compatibility notes cover only changes in the ApsaraDB for MongoDB kernel, not changes in instance management features.

    Major database version

    Compatibility changes

    MongoDB 8.3

    • If you created views or collection validators using expressions, parameters, or variables introduced in MongoDB 8.3, these views may fail or objects may not validate or evaluate correctly after downgrading.

    • MongoDB 8.3 introduces new validation semantics to mark collections as “validated.” This semantics is incompatible with versions earlier than 8.3. Downgrade attempts will fail if validated collections exist.

    • Starting in MongoDB 8.3, when documents constructed by the $facet stage exceed the 100 MB limit, MongoDB returns error code 146 instead of 4031700 for the ExceededMemoryLimit error. If your application, driver, or tool explicitly checks for 4031700, you need to update your code to detect the new ExceededMemoryLimit error code.

    • When downgrading from MongoDB 8.3 to an earlier version, the activeBalancerWindowDOW (day-of-week balancer window) configuration becomes unavailable.

    • The removeShard command is deprecated. Use the new commands startShardDraining, stopShardDraining, shardDrainingStatus, and commitShardRemoval to control shard removal. These support pausing and resuming migration at any time.

    • On sharded clusters, DDL operations and applyOps must now run through mongos and cannot execute directly on shard nodes.

    • The default value of 2dsphereVersion increases from 3 to 4. To downgrade the feature compatibility version (FCV) below 8.3, delete all version 4 2dsphere indexes first.

    • Starting in MongoDB 8.3 (and also 8.0.18, 7.0.29), composite wildcard indexes enforce stricter validation rules for the wildcardProjection specification. Existing indexes continue to work even if they don’t meet the new requirements, but you cannot create new indexes that violate them.

    • For time series collections, refineCollectionShardKey now requires the shard key to reference logical metadata and the time field, and no longer accepts the underlying bucket format. Indexes cannot be named _id_. The timeField name cannot start with $.

    • The serverStatus output removes the service field.

    • Removes the config.csrs.indexes system collection.

    For more information about MongoDB 8.3, see Compatibility Changes in MongoDB 8.3.

    MongoDB 8.0

    • Avoid using tcmallocAggressiveMemoryDecommit.

    • The tcmallocReleaseRate parameter lets you specify a memory release rate. ApsaraDB for MongoDB sets this to 10 MB/s by default.

    • When null is used as a query condition, MongoDB no longer matches undefined values.

    • Avoid using index filters.

    • For time series collections, avoid using timeField as the sharding key.

    • Avoid using the cleanupOrphaned command.

    • Do not run concurrent compact commands on the same collection.

    • Before upgrading to MongoDB 8.0, rename or delete any non-time-series collection named system.buckets.

    For more information about MongoDB 8.0, see Compatibility Changes in MongoDB 8.0.

    MongoDB 7.0

    • No compatibility issues exist when upgrading to MongoDB 7.0.

    • To downgrade from MongoDB 7.0 to an earlier major version, first remove features introduced in 7.0, such as:

      • Delete all columnar indexes (columnar indexes).

      • Unregister cluster parameters set using the setClusterParameter command. For details, see setClusterParameter.

      • Delete all collections created with the encryptedFields option.

      • Delete all compound wildcard indexes (Compound wildcard indexes).

    For more information about MongoDB 7.0, see Compatibility Changes in MongoDB 7.0.

    MongoDB 6.0

    • If an aggregation pipeline uses more than 100 MB of memory, MongoDB writes data to temporary files on disk by default. To change this behavior, set the global parameter allowDiskUseByDefault to false.

      Versions earlier than 6.0 require explicitly specifying { allowDiskUse: true } to write data to temporary disk files.

    • When using dropIndexes with the wildcard *, MongoDB does not drop the _id index or the shard key index. For more information, see dropIndexes.

    • Mongo Shell is no longer supported. Use mongosh instead.

    • Operators such as $explain, $hint, $max, and $maxTimeMS are no longer supported.

    • When the TTL index expireAfterSeconds is set to NaN, it is treated as 0, which may immediately expire documents.

    • The SCRAM-SHA-1 authentication method is no longer supported.

    • The reIndex command and its corresponding reIndex() method are no longer supported.

    For more information about MongoDB 6.0, see Compatibility Changes in MongoDB 6.0.

    MongoDB 5.0

    • The Read Concern level for secondary nodes changes from available to local. For more information, see Read Concern.

    • The default Write Concern changes from 1 to majority.

      Important

      This change may degrade write performance. Confirm the impact before upgrading. You can also use the setDefaultRWConcern command to change the default writeConcern.

    • db.collection.ensureIndex() is no longer supported. Use db.collection.createIndex() instead.

    • Parameters for the saslStart and saslContinue commands are now strictly validated and are incompatible with mgo. saslContinue requires only conversationId and payload, but mgo provides an extra mechanism parameter. For more information, see mgo.

    • Removes geoSearch.

    For more information about MongoDB 5.0, see Compatibility Changes in MongoDB 5.0.

    MongoDB 4.4

    • compact no longer supports the force option. For more information, see compact.

    • geoSearch is no longer supported. For more information, see geoSearch.

    • Indexes can now be created simultaneously on both primary and secondary databases, reducing replication lag during index creation. Secondaries remain up to date even while indexes are being built.

    For more information about MongoDB 4.4, see Compatibility Changes in MongoDB 4.4.

    MongoDB 4.2

    • geoNear is no longer supported. Use $geoNear (aggregation) instead. For more information, see $geoNear (aggregation).

    • repairDatabase is no longer supported.

    • cloneCollection is removed and no longer supported. Use mongoexport and mongoimport instead. For more information, see mongoexport and mongoimport.

    • afterClusterTime is no longer supported. For more information, see afterClusterTime.

    • Open source MongoDB 4.2+ drivers enable Retryable Writes by default. For more information, see Retryable Writes.

    • Removes group, copydb, and clone.

    For more information about MongoDB 4.2, see MongoDB 4.2 compatibility update notes.

    MongoDB 4.0

    • reIndex acquires a global write lock until index rebuilding completes. For more information, see reIndex.

    • copydb and clone are no longer supported.

    For more information about MongoDB 4.0, see MongoDB 4.0 compatibility update notes.

    MongoDB 3.6

    • aggregate no longer returns a single document. It returns a cursor. You can use the cursor to specify batch size. For more information about aggregate, see aggregate.

    • $type: "array" now detects array-type documents directly, not just nested arrays. For more information about $type, see $type.

    • Array sorting behavior changes as follows:

      • find adds a sort option to provide detailed sort results. For more information about find, see find.

      • The $sort stage in $sort(aggregation) has a 100 MB memory limit. For more information, see $sort (aggregation).

    • When updating multiple fields in one operation, new fields are added in lexicographic order. For more information, see $set.

    • The snapshot query option is no longer supported.

    For more information about MongoDB 3.6, see MongoDB 3.6 compatibility update notes.

    MongoDB 3.4

    • group is no longer supported. Use db.collection.aggregate() or db.collection.mapReduce() instead. For more information, see db.collection.aggregate() and db.collection.mapReduce().

    • Use the $in expression to match the update operation with + upsert: true.

      Example:

      db.c.drop()
db.c.update({a:{$in:[1]}},{$addToSet:{a:2}},{upsert:true}) // Fails in MongoDB 3.4, but succeeds in earlier versions.
db.c.update({a:{$elemMatch:{$in:[2]}}},{$addToSet:{a:2}},{upsert:true}) // Succeeds in MongoDB 3.4.

      For more information about update, see update.

    For more information about MongoDB 3.4, see MongoDB 3.4 compatibility changes.

    Related APIs

    Interface

    Description

    UpgradeDBInstanceEngineVersion

    Upgrades the major database version of an ApsaraDB for MongoDB instance.