ApsaraDB for MongoDB:Notes on major MongoDB database version upgrades

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.