ApsaraDB for MongoDB:ApsaraDB for MongoDB major version upgrade

Standalone instance

Replica set instance

Cloud disk instances (general-purpose cloud disk, dedicated with cloud disks):

Local disk instances (general-purpose local disks, dedicated local disks, dedicated host):

Sharded cluster instance

Dedicated with cloud disks:

Local disk instances (general-purpose local disks, dedicated local disks, dedicated host):

Cross-architecture and cross-storage-class migration

To upgrade across instance architectures or storage types (for example, from a local disk instance to a cloud disk instance), create a new instance running the target version and use Data Transmission Service (DTS) to migrate your data.

• Create an instance

Migrate data using the appropriate DTS topic:

• Standalone instance to any architecture

• Replica set to replica set or sharded cluster

• Self-managed sharded cluster to ApsaraDB replica set or sharded cluster

MongoDB 8.0

• tcmallocAggressiveMemoryDecommit is not recommended.

• Use tcmallocReleaseRate to control the memory release rate. The default in ApsaraDB for MongoDB is 10 MB/s.

• Comparisons to null no longer match undefined values. For example, { name: null } returns documents where name is null, but not where name is undefined.

• Index filters are not recommended.

• timeField is not recommended as a shard key for time series collections.

• The cleanupOrphaned command is not recommended.

• Multiple compact commands cannot run concurrently on a collection.

• Rename or delete any non-time-series system.buckets collections before upgrading.

For the full list, see Compatibility changes in MongoDB 8.0.

MongoDB 7.0

No compatibility issues exist when upgrading to MongoDB 7.0.

If you need to downgrade from 7.0 to an earlier version, remove the following before downgrading:

• All columnar indexes

• Cluster parameters registered with setClusterParameter — see setClusterParameter

• All collections created with the encryptedFields option

• All compound wildcard indexes

For the full list, see Compatibility changes in MongoDB 7.0.

MongoDB 6.0

• Aggregation pipeline disk spill: If a pipeline processes more than 100 MB of data, MongoDB writes to temporary disk storage by default. To disable this, set allowDiskUseByDefault to false. In versions earlier than 6.0, use { allowDiskUse: true } to enable disk spill explicitly.

• dropIndexes with * drops all indexes except the _id index and the last remaining shard key index — see dropIndexes.

• The mongo shell is deprecated. Use mongosh instead.

• Operators $explain, $hint, $max, and $maxTimeMS are deprecated.

• If expireAfterSeconds is set to NaN or 0 on a TTL index, expired documents may be evicted immediately.

• The SCRAM-SHA-1 authentication mechanism is deprecated.

• The reIndex command and reIndex() method are deprecated.

For the full list, see Compatibility changes in MongoDB 6.0.

MongoDB 5.0

• Read concern on secondary nodes: The default read concern level on secondary nodes changes from available to local — see Read Concern.

• Default write concern changes from `{w:1}` to `{w:majority}`: This is the highest-impact change in MongoDB 5.0. See the write performance impact section below.

• db.collection.ensureIndex() is deprecated. Use db.collection.createIndex() instead.

• The saslStart and saslContinue commands now strictly validate parameters. The Go driver mgo adds an extra mechanism parameter to saslContinue that is not supported — see mgo.

• The geoSearch command is deprecated.

For the full list, see Compatibility changes in MongoDB 5.0.

MongoDB 4.4

• The force option is deprecated in the compact command — see compact.

• The geoSearch command is deprecated — see geoSearch.

• Indexes can be created on both the primary and secondary nodes concurrently, reducing the latency caused by index creation. During index builds, the secondary node can still access the latest data.

For the full list, see Compatibility changes in MongoDB 4.4.

MongoDB 4.2

• The geoNear command is deprecated. Use $geoNear in an aggregation pipeline instead — see $geoNear.

• The repairDatabase command is deprecated.

• The cloneCollection command is deprecated. Use mongoexport and mongoimport instead — see mongoexport and mongoimport.

• The afterClusterTime read concern option is deprecated — see Read Operations and afterClusterTime.

• Drivers compatible with MongoDB 4.2 or later enable retryable writes by default — see Retryable Writes.

• The group, copydb, and clone commands are deprecated.

For the full list, see Compatibility changes in MongoDB 4.2.

MongoDB 4.0

• The reIndex command acquires a global exclusive (W) lock and blocks all other operations until the index rebuild completes — see reIndex.

• The copydb and clone commands are deprecated.

For the full list, see Compatibility changes in MongoDB 4.0.

MongoDB 3.6

• Running aggregate without a cursor option to return a single document is deprecated. Include the cursor option unless you use the explain option — see aggregate.

• $type: "array" now returns only documents where the field itself is an array. In versions earlier than 3.6, it also returned documents where the field was an array containing at least one element of array type — see $type.

• The find command now accepts an optional sort option — see find.

• $sort in an aggregation pipeline has a 100 MB memory limit — see $sort (aggregation).

• In multi-field update operations, fields are added in lexicographical order — see $set.

• The snapshot query option is deprecated.

For the full list, see Compatibility changes in MongoDB 3.6.

MongoDB 3.4

• The group command is deprecated. Use db.collection.aggregate() or db.collection.mapReduce() instead — see db.collection.aggregate() and db.collection.mapReduce().

• The $in expression with upsert: true has updated behavior for determining whether matching documents exist:

  db.c.drop()
  // Cannot insert in MongoDB 3.4; can insert in versions earlier than 3.4
  db.c.update({a:{$in:[1]}},{$addToSet:{a:2}},{upsert:true})
  // Can insert in MongoDB 3.4
  db.c.update({a:{$elemMatch:{$in:[2]}}},{$addToSet:{a:2}},{upsert:true})

For the full list, see Compatibility changes in MongoDB 3.4.