Docs4dev
Docs
mongodb / v3.6 / reference / release-notes-2.6-compatibility.html

Compatibility Changes in MongoDB 2.6

On this page

The following 2.6 changes can affect the compatibility with older versions of MongoDB. See Release Notes for MongoDB 2.6 for the full list of the 2.6 changes.

Index Changes

Enforce Index Key Length Limit

Description

MongoDB 2.6 implements a stronger enforcement of the limit on index key.

Creating indexes will error if an index key in an existing document exceeds the limit:

Inserts will error:

  • db.collection.insert() and other operations that perform inserts (e.g. db.collection.save() and db.collection.update() with upsert that result in inserts) will fail to insert if the new document has an indexed field whose corresponding index entry exceeds the limit. Previous versions of MongoDB would insert but not index such documents.
  • mongorestore and mongoimport will fail to insert if the new document has an indexed field whose corresponding index entry exceeds the limit.

Updates will error:

  • db.collection.update() and db.collection.save() operations on an indexed field will error if the updated value causes the index entry to exceed the limit.
  • If an existing document contains an indexed field whose index entry exceeds the limit, updates on other fields that result in the relocation of a document on disk will error.

Chunk Migration will fail:

  • Migrations will fail for a chunk that has a document with an indexed field whose index entry exceeds the limit.
  • If left unfixed, the chunk will repeatedly fail migration, effectively ceasing chunk balancing for that collection. Or, if chunk splits occur in response to the migration failures, this response would lead to unnecessarily large number of chunks and an overly large config databases.

Secondary members of replica sets will warn:

  • Secondaries will continue to replicate documents with an indexed field whose corresponding index entry exceeds the limit on initial sync but will print warnings in the logs.
  • Secondaries allow index build and rebuild operations on a collection that contains an indexed field whose corresponding index entry exceeds the limit but with warnings in the logs.
  • With mixed version replica sets where the secondaries are version 2.6 and the primary is version 2.4, secondaries will replicate documents inserted or updated on the 2.4 primary, but will print error messages in the log if the documents contain an indexed field whose corresponding index entry exceeds the limit.
Solution
Run db.upgradeCheckAllDBs() to find current keys that violate this limit and correct as appropriate. Preferably, run the test before upgrading; i.e. connect the 2.6 mongo shell to your MongoDB 2.4 database and run the method.

If you have an existing data set and want to disable the default index key length validation so that you can upgrade before resolving these indexing issues, use the failIndexKeyTooLong parameter.

Index Specifications Validate Field Names

Description

In MongoDB 2.6, create and re-index operations fail when the index key refers to an empty field, e.g. "a..b" : 1 or the field name starts with a dollar sign ($).

Previous versions of MongoDB allow the index.

Solution
Run db.upgradeCheckAllDBs() to find current keys that violate this limit and correct as appropriate. Preferably, run the test before upgrading; i.e. connect the 2.6 mongo shell to your MongoDB 2.4 database and run the method.

ensureIndex and Existing Indexes

Description

db.collection.ensureIndex() now errors:

  • if you try to create an existing index but with different options; e.g. in the following example, the second db.collection.ensureIndex() will error.

    db.mycollection.ensureIndex( { x: 1 } )
db.mycollection.ensureIndex( { x: 1 }, { unique: 1 } )

  • if you specify an index name that already exists but the key specifications differ; e.g. in the following example, the second db.collection.ensureIndex() will error.

    db.mycollection.ensureIndex( { a: 1 }, { name: "myIdx" } )
db.mycollection.ensureIndex( { z: 1 }, { name: "myIdx" } )

Previous versions did not create the index but did not error.

Write Method Acknowledgements

Description
The mongo shell write methods db.collection.insert(), db.collection.update(), db.collection.save() and db.collection.remove() now integrate the write concern directly into the method rather than with a separate getLastError command to provide acknowledgement of writes whether run interactively in the mongo shell or non-interactively in a script. In previous versions, these methods exhibited a “fire-and-forget” behavior. [1]
  • Existing scripts for the mongo shell that used these methods will now wait for acknowledgement, which take longer than the previous “fire-and-forget” behavior.
  • The write methods now return a WriteResult object that contains the results of the operation, including any write errors and write concern errors, and obviates the need to call getLastError command to get the status of the results. See db.collection.insert(), db.collection.update(), db.collection.save() and db.collection.remove() for details.
  • In sharded environments, mongos no longer supports “fire-and-forget” behavior. This limits throughput when writing data to sharded clusters.
[1] In previous versions, when using the mongo shell interactively, the mongo shell automatically called the getLastError command after a write method to provide acknowledgement of the write. Scripts, however, would observe “fire-and-forget” behavior in previous versions unless the scripts included an explicit call to the getLastError command after a write method.
Solution

Scripts that used these mongo shell methods for bulk write operations with “fire-and-forget” behavior should use the Bulk() methods.

In sharded environments, applications using any driver or mo