Compatibility Changes in MongoDB 2.6

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

Index Changes

Enforce Index Key Length Limit

  • Description
  • MongoDB 2.6 implements a stronger enforcement of the limit onindex key.

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

  • db.collection.ensureIndex(),db.collection.reIndex(), compact, andrepairDatabase will error and not create the index.Previous versions of MongoDB would create the index but not indexsuch documents.

  • Because db.collection.reIndex(), compact,and repairDatabase drop all the indexes from acollection and then recreate them sequentially, the error from theindex key limit prevents these operations from rebuilding anyremaining indexes for the collection and, in the case of therepairDatabase command, from continuing with theremainder of the process.Inserts will error:

  • db.collection.insert() and other operations that performinserts (e.g. db.collection.save() anddb.collection.update() with upsert that result ininserts) will fail to insert if the new document has an indexedfield whose corresponding index entry exceeds the limit.Previous versions of MongoDB would insert but not index suchdocuments.

  • mongorestore and mongoimport will fail toinsert if the new document has an indexed field whosecorresponding index entry exceeds the limit.Updates will error:

  • db.collection.update() anddb.collection.save() operations on an indexed field willerror if the updated value causes the index entry to exceed thelimit.

  • If an existing document contains an indexed field whose indexentry exceeds the limit, updates on other fields that result inthe relocation of a document on disk will error.Chunk Migration will fail:

  • Migrations will fail for a chunk that has a document with anindexed field whose index entry exceeds the limit.

  • If left unfixed, the chunk will repeatedly fail migration,effectively ceasing chunk balancing for that collection. Or, ifchunk splits occur in response to the migration failures, thisresponse would lead to unnecessarily large number of chunks and anoverly large config databases.Secondary members of replica sets will warn:

  • Secondaries will continue to replicate documents with an indexedfield whose corresponding index entry exceeds the limit on initialsync but will print warnings in the logs.

  • Secondaries allow index build and rebuild operations on acollection that contains an indexed field whose correspondingindex entry exceeds the limit but with warnings in the logs.
  • With mixed version replica sets where the secondaries areversion 2.6 and the primary is version 2.4, secondaries willreplicate documents inserted or updated on the 2.4 primary, butwill print error messages in the log if the documents contain anindexed field whose corresponding index entry exceeds the limit.
    • Solution
    • Run db.upgradeCheckAllDBs() to find current keys thatviolate this limit and correct as appropriate. Preferably, run thetest before upgrading; i.e. connect the 2.6 mongo shellto your MongoDB 2.4 database and run the method.

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

Index Specifications Validate Field Names

  • Description

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

    • db.collection.ensureIndex() will not create a new indexwith an invalid or empty key name.
    • db.collection.reIndex(), compact, andrepairDatabase will error if an index exists with aninvalid or empty key name.
    • Chunk migration will fail if an index exists with aninvalid or empty key name.Previous versions of MongoDB allow the index.

  • Solution

  • Run db.upgradeCheckAllDBs() to find current keys thatviolate this limit and correct as appropriate. Preferably, run thetest before upgrading; i.e. connect the 2.6 mongo shellto your MongoDB 2.4 database and run the method.

ensureIndex and Existing Indexes

  1. db.mycollection.ensureIndex( { x: 1 } )
  2. db.mycollection.ensureIndex( { x: 1 }, { unique: 1 } )
  • if you specify an index name that already exists but the keyspecifications differ; e.g. in the following example, the seconddb.collection.ensureIndex() will error.
  1. db.mycollection.ensureIndex( { a: 1 }, { name: "myIdx" } )
  2. db.mycollection.ensureIndex( { z: 1 }, { name: "myIdx" } )

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

Write Method Acknowledgements

  • Existing scripts for the mongo shell that used thesemethods will now wait for acknowledgement, which take longer thanthe previous “fire-and-forget” behavior.
  • The write methods now return a WriteResult object thatcontains the results of the operation, including any write errorsand write concern errors, and obviates the need to callgetLastError 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 datato sharded clusters.
[1]In previous versions, when using the mongo shellinteractively, the mongo shell automatically called thegetLastError command after a write method to provideacknowledgement of the write. Scripts, however, would observe “fire-and-forget”behavior in previous versions unless the scripts included anexplicit call to the getLastError command after awrite method.
  • Solution
  • Scripts that used these mongo shell methods for bulk writeoperations with “fire-and-forget” behavior should use theBulk() methods.

In sharded environments, applications using any driver ormongo shell should use Bulk() methods for optimalperformance when inserting or modifying groups of documents.

For example, instead of:

  1. for (var i = 1; i <= 1000000; i++) {
  2.     db.test.insert( { x : i } );
  3. }

In MongoDB 2.6, replace with Bulk() operation:

  1. var bulk = db.test.initializeUnorderedBulkOp();
  2.  
  3. for (var i = 1; i <= 1000000; i++) {
  4.     bulk.insert( { x : i} );
  5. }
  6.  
  7. bulk.execute( { w: 1 } );

Bulk method returns a BulkWriteResult object that containsthe result of the operation.

See also

New Write Operation Protocol,Bulk(),Bulk.execute(),db.collection.initializeUnorderedBulkOp(),db.collection.initializeOrderedBulkOp()

db.collection.aggregate() Change

  • Description
  • The db.collection.aggregate() method in themongo shell defaults to returning a cursor to the resultsset. This change enables the aggregation pipeline to return resultsets of any size and requires cursor iteration to access the resultset. For example:
  1. var myCursor = db.orders.aggregate( [
  2.     {
  3.       $group: {
  4.          _id: "$cust_id",
  5.          total: { $sum: "$price" }
  6.       }
  7.     }
  8. ] );
  9.  
  10. myCursor.forEach( function(x) { printjson (x); } );

Previous versions returned a single document with a field resultsthat contained an array of the result set, subject to the BSONDocument size limit. Accessing the resultset in the previous versions of MongoDB required accessing theresults field and iterating the array. For example:

  1. var returnedDoc = db.orders.aggregate( [
  2.     {
  3.       $group: {
  4.          _id: "$cust_id",
  5.          total: { $sum: "$price" }
  6.       }
  7.     }
  8. ] );
  9.  
  10. var myArray = returnedDoc.result; // access the result field
  11.  
  12. myArray.forEach( function(x) { printjson (x); } );
  • Solution
  • Update scripts that currently expectdb.collection.aggregate() to return a document with aresults array to handle cursors instead.

See also

Aggregation Enhancements,db.collection.aggregate(),

Write Concern Validation

  • Description
  • Specifying a write concern that includes j: true to amongod or mongos instance running with—nojournal option now errors. Previous versions wouldignore the j: true.
  • Solution
  • Either remove the j: true specification from the write concern whenissued against a mongod or mongos instancewith —nojournal or run mongod ormongos with journaling.

Security Changes

New Authorization Model

  • Description

  • MongoDB 2.6 authorization model changes howMongoDB stores and manages user privilege information:

    • Before the upgrade, MongoDB 2.6 requires at least one user in theadmin database.
    • MongoDB versions using older models cannot create/modify users orcreate user-defined roles.
  • Solution
  • Ensure that at least one user exists in the admin database. If nouser exists in the admin database, add a user. Then upgrade toMongoDB 2.6. Finally, upgrade the user privilege model. SeeUpgrade MongoDB to 2.6.

Important

Before upgrading the authorization model, you should first upgradeMongoDB binaries to 2.6. For sharded clusters, ensure that allcluster components are 2.6. If there are users in any database, be sureyou have at least one user in the admin database with the roleuserAdminAnyDatabasebefore upgrading the MongoDBbinaries.

See also

Security Improvements

SSL Certificate Hostname Validation

  • Description
  • The SSL certificate validation now checks the Common Name (CN)and the Subject Alternative Name (SAN) fields to ensure thateither the CN or one of the SAN entries matches the hostnameof the server. As a result, if you currently use SSL and _neither_the CN nor any of the SAN entries of your current SSLcertificates match the hostnames, upgrading to version 2.6 willcause the SSL connections to fail.
  • Solution

  • To allow for the continued use of these certificates, MongoDBprovides the allowInvalidCertificates setting. Thesetting is available for:

Warning

The allowInvalidCertificates settingbypasses the other certificate validation, such as checks forexpiration and valid signatures.

2dsphere Index Version 2

  • Description
  • MongoDB 2.6 introduces a version 2 of the 2dsphere index. If a document lacks a 2dsphereindex field (or the field is null or an empty array), MongoDBdoes not add an entry for the document to the 2dsphere index.For inserts, MongoDB inserts the document but does not add to the2dsphere index.

Previous version would not insert documents where the 2dsphereindex field is a null or an empty array. For documents that lackthe 2dsphere index field, previous versions would insert andindex the document.

  • Solution
  • To revert to old behavior, create the 2dsphere index with {"2dsphereIndexVersion" : 1 } to create a version 1 index. However,version 1 index cannot use the new GeoJSON geometries.

See also

Versions

Log Messages

Timestamp Format Change

  • Description
  • Each message now starts with the timestamp format given in Time Format Changes.Previous versions used the ctime format.
  • Solution
  • MongoDB adds a new option —timeStampFormat which supportstimestamp format in ctime,iso8601-utc, and iso8601-local (new default).

Package Configuration Changes

Default bindIp for RPM/DEB Packages

  • Description
  • In the official MongoDB packages in RPM (Red Hat, CentOS, FedoraLinux, and derivatives) and DEB (Debian, Ubuntu, and derivatives),the default bindIp value attaches MongoDB components tothe localhost interface only. These packages set this default inthe default configuration file (i.e. /etc/mongod.conf.)
  • Solution
  • If you use one of these packages and have not modified the default/etc/mongod.conf file, you will need to set bindIpbefore or during the upgrade.

There is no default bindIp setting in any other official MongoDBpackages.

SNMP Changes

  • Description
    • The IANA enterprise identifier for MongoDB changed from37601 to 34601.
    • MongoDB changed the MIB field name globalopcounts toglobalOpcounts.
  • Solution
    • Users of SNMP monitoring must modify their SNMP configuration(i.e. MIB) from 37601 to 34601.
    • Update references to globalopcounts to globalOpcounts.

Remove Method Signature Change

  • Description
  • db.collection.remove() requires a query document as aparameter. In previous versions, the method invocation without aquery document deleted all documents in a collection.
  • Solution
  • For existing db.collection.remove() invocations without aquery document, modify the invocations to include an empty documentdb.collection.remove({}).

Update Operator Syntax Validation

  • Description
  1. { $set: { } }
  1. { $set: { a: 5 }, $set: { b: 5 } }

Updates Enforce Field Name Restrictions

  • Description
    • Updates cannot use update operators (e.g $set) to target fields with empty fieldnames (i.e. "").
    • Updates no longer support saving field names that contain a dot(.) or a field name that starts with a dollar sign ($).
  • Solution
    • For existing documents that have fields with empty names "",replace the whole document. See db.collection.update()and db.collection.save() for details on replacing anexisting document.
    • For existing documents that have fields with names that contain adot (.), either replace the whole document or unset the field. To find fields whose names contain a dot, rundb.upgradeCheckAllDBs().
    • For existing documents that have fields with names that start witha dollar sign ($), unset or rename those fields. To find fields whose names start with adollar sign, run db.upgradeCheckAllDBs().

See New Write Operation Protocol for the changes to the writeoperation protocol, and Insert and Update Improvements for thechanges to the insert and update operations. Also consider thedocumentation of the Restrictions on Field Names.

Query and Sort Changes

Enforce Field Name Restrictions

  • Description
  • Queries cannot specify conditions on fields with names that startwith a dollar sign ($).
  • Solution
  • Unset or rename existingfields whose names start with a dollar sign ($). Rundb.upgradeCheckAllDBs() to find fields whosenames start with a dollar sign.

Sparse Index and Incomplete Results

  • Description
  • If a sparse index results in anincomplete result set for queries and sort operations, MongoDB willnot use that index unless a hint() explicitlyspecifies the index.

For example, the query { x: { $exists: false } } will no longeruse a sparse index on the x field, unless explicitly hinted.

  • Solution
  • To override the behavior to use the sparse index and returnincomplete results, explicitly specify the index with ahint().

See Sparse Index On A Collection Cannot Return Complete Results for an example that detailsthe new behavior.

sort() Specification Values

  • Description

  • The sort() method only accepts the followingvalues for the sort keys:

    • 1 to specify ascending order for a field,
    • -1 to specify descending order for a field, or
    • $meta expression to specify sort by the text searchscore.Any other value will result in an error.

Previous versions also accepted either true or false forascending.

  • Solution
  • Update sort key values that use true or false to 1.

skip() and _id Queries

  • Description
  • Equality match on the _id field obeys skip().

Previous versions ignored skip() when performingan equality match on the _id field.

explain() Retains Query Plan Cache

In previous versions, explain() would have theside effect of clearing the query plan cache for that query shape.

See also

The PlanCache() reference.

Geospatial Changes

$maxDistance Changes

In previous version, $maxDistance could be either insideor outside the $near document.

  • Solution
    • Update any existing $near queries on GeoJSON data thatcurrently have the $maxDistance outside the$near document
    • Update any existing queries where $maxDistance is anegative value.

Deprecated $uniqueDocs

  • Description
  • MongoDB 2.6 deprecates $uniqueDocs, and geospatial queriesno longer return duplicated results when a document matches thequery multiple times.

Stronger Validation of Geospatial Queries

  • Description
  • MongoDB 2.6 enforces a stronger validation of geospatial queries,such as validating the options or GeoJSON specifications, and errorsif the geospatial query is invalid. Previous versionsallowed/ignored invalid options.

Query Operator Changes

$not Query Behavior Changes

  • Description

    • Queries with $not expressions on an indexed field now match:

      • Documents that are missing the indexed field. Previous versionswould not return these documents using the index.
      • Documents whose indexed field value is a different type thanthat of the specified value. Previous versions would not returnthese documents using the index.For example, if a collection orders contains the followingdocuments:
  1. { _id: 1, status: "A", cust_id: "123", price: 40 }
  2. { _id: 2, status: "A", cust_id: "xyz", price: "N/A" }
  3. { _id: 3, status: "D", cust_id: "xyz" }

If the collection has an index on the price field:

  1. db.orders.ensureIndex( { price: 1 } )

The following query uses the index to search for documents whereprice is not greater than or equal to 50:

  1. db.orders.find( { price: { $not: { $gte: 50 } } } )

In 2.6, the query returns the following documents:

  1. { "_id" : 3, "status" : "D", "cust_id" : "xyz" }
  2. { "_id" : 1, "status" : "A", "cust_id" : "123", "price" : 40 }
  3. { "_id" : 2, "status" : "A", "cust_id" : "xyz", "price" : "N/A" }

In previous versions, indexed plans would onlyreturn matching documents where the type of the field matches thetype of the query predicate:

  1. { "_id" : 1, "status" : "A", "cust_id" : "123", "price" : 40 }

If using a collection scan, previous versions would return thesame results as those in 2.6.

  • MongoDB 2.6 allows chaining of $not expressions.

null Comparison Queries

  • Description
    • $lt and $gt comparisons to null nolonger match documents that are missing the field.
    • null equality conditions on array elements (e.g. "a.b":null) no longer match document missing the nested field a.b(e.g. a: [ 2, 3 ]).
    • null equality queries (i.e. field: null ) now match fieldswith values undefined.

$all Operator Behavior Change

  • Description
    • The $all operator is now equivalent to an $andoperation of the specified values. This change in behavior canallow for more matches than previous versions when passed an arrayof a single nested array (e.g. [ [ "A" ] ]). When passed anarray of a nested array, $all can now match documentswhere the field contains the nested array as an element (e.g.field: [ [ "A" ], … ]), or the field equals the nestedarray (e.g. field: [ "A", "B" ]). Earlier version could onlymatch documents where the field contains the nested array.
    • The $all operator returns no match if the array fieldcontains nested arrays (e.g. field: [ "a", ["b"] ]) and$all on the nested field is the element of the nestedarray (e.g. "field.1": { $all: [ "b" ] }). Previous versionswould return a match.

$mod Operator Enforces Strict Syntax

In previous versions, if passed an array with one element, the$mod operator uses 0 as the second element, and ifpassed an array with more than two elements, the $modignores all but the first two elements. Previous versions do returnan error when passed an empty array.

  • Solution

  • Ensure that the array passed to $mod contains exactly twoelements:

    • If the array contains the a single element, add 0 as thesecond element.
    • If the array contains more than two elements, remove the extraelements.

$where Must Be Top-Level

  • Description
  • $where expressions can now only be at top level and cannot benested within another expression, such as $elemMatch.
  • Solution
  • Update existing queries that nest $where.

$exists and notablescan

If the MongoDB server has disabled collection scans, i.e.notablescan, then $exists queries that have noindexed solution will error.

MinKey and MaxKey Queries

  • Description
  • Equality match for either MinKey orMaxKey no longer match documents missing the field.

Nested Array Queries with $elemMatch

  • Description
  • The $elemMatch query operator no longer traversesrecursively into nested arrays.

For example, if a collection test contains the followingdocument:

  1. { "_id": 1, "a" : [ [ 1, 2, 5 ] ] }

In 2.6, the following $elemMatch query does not match thedocument:

  1. db.test.find( { a: { $elemMatch: { $gt: 1, $lt: 5 } } } )
  • Solution
  • Update existing queries that rely upon the old behavior.

Text Search Compatibility

MongoDB does not support the use of the $text query operatorin mixed sharded cluster deployments that contain both version 2.4and version 2.6 shards. See Upgrade MongoDB to 2.6 forupgrade instructions.

Replica Set/Sharded Cluster Validation

Shard Name Checks on Metadata Refresh

  • Description
  • For sharded clusters, MongoDB 2.6 disallows a shard from refreshingthe metadata if the shard name has not been explicitly set.

For mixed sharded cluster deployments that contain both version 2.4and version 2.6 shards, this change can cause errors when migratingchunks from version 2.4 shards to version 2.6 shards if theshard name is unknown to the version 2.6 shards. MongoDB does notsupport migrations in mixed sharded cluster deployments.

Replica Set Vote Configuration Validation

  • Description
  • MongoDB now deprecates giving any replica set member morethan a single vote. During configuration,local.system.replset.members[n].votes should only have avalue of 1 for voting members and 0 for non-voting members. MongoDBtreats values other than 1 or 0 as a value of 1 and produces awarning message.
  • Solution
  • Update local.system.replset.members[n].votes with valuesother than 1 or 0 to 1 or 0 as appropriate.

Time Format Changes

MongoDB now uses iso8601-local when formatting time data in manyoutputs. This format follows the templateYYYY-MM-DDTHH:mm:ss.mmm<+/-Offset>. For example, 2014-03-04T20:13:38.944-0500.

This change impacts all clients usingExtended JSON in Strict mode, such asmongoexport and the REST and HTTP Interfaces.

Other Resources