Release Notes for MongoDB 2.2

Upgrading

MongoDB 2.2 is a production release series and succeeds the 2.0production release series.

MongoDB 2.0 data files are compatible with 2.2-series binaries without anyspecial migration process. However, always perform the upgrade process for replicasets and sharded clusters using the procedures that follow.

Synopsis

  • mongod, 2.2 is a drop-in replacement for 2.0 and 1.8.

  • Check your driver documentation forinformation regarding required compatibility upgrades, and alwaysrun the recent release of your driver.

Typically, only users running with authentication, will need toupgrade drivers before continuing with the upgrade to 2.2.

  • For all deployments using authentication, upgrade thedrivers (i.e. client libraries), before upgrading themongod instance or instances.

  • For all upgrades of sharded clusters:

    • turn off the balancer during the upgrade process. See theDisable the Balancer section for moreinformation.
    • upgrade all mongos instances before upgrading anymongod instances.

Other than the above restrictions, 2.2 processes can interoperate with2.0 and 1.8 tools and processes. You can safely upgrade themongod and mongos components of a deploymentone by one while the deployment is otherwise operational. Be sure toread the detailed upgrade procedures below before upgrading productionsystems. [1]

[1]To minimize the interruption caused byelection process, always upgrade thesecondaries of the set first, then step down the primary, and then upgrade the primary.

Upgrading a Standalone mongod

  • Download binaries of the latest release in the 2.2 series from theMongoDB Download Page.
  • Shutdown your mongod instance. Replace the existingbinary with the 2.2 mongod binary and restart MongoDB.

Upgrading a Replica Set

You can upgrade to 2.2 by performing a “rolling”upgrade of the set by upgrading the members individually while theother members are available to minimize downtime. Use the followingprocedure:

  • Upgrade the secondary members of the set one at a time byshutting down the mongod and replacing the 2.0 binarywith the 2.2 binary. After upgrading a mongod instance,wait for the member to recover to SECONDARY statebefore upgrading the next instance.To check the member’s state, issue rs.status() in themongo shell.

  • Use the mongo shell method rs.stepDown() tostep down the primary to allow the normal failover procedure. rs.stepDown()expedites the failover procedure and is preferable to shutting downthe primary directly.

Once the primary has stepped down and another member has assumedPRIMARY state, as observed in the output ofrs.status(), shut down the previous primary and replacemongod binary with the 2.2 binary and start the newprocess.

Note

Replica set failover is not instant but willrender the set unavailable to read or accept writesuntil the failover process completes. Typically this takes10 seconds or more. You may wish to plan the upgrade duringa predefined maintenance window.

Upgrading a Sharded Cluster

Use the following procedure to upgrade a sharded cluster:

Note

Balancing is not currently supported in mixed 2.0.x and 2.2.0deployments. Thus you will want to reach a consistent version for allshards within a reasonable period of time, e.g. same-day.See SERVER-6902 for more information.

Changes

Major Features

Aggregation Framework

The aggregation framework makes it possible to do aggregationoperations without needing to use map-reduce. Theaggregate command exposes the aggregation framework, and theaggregate() helper in the mongo shellprovides an interface to these operations. Consider the followingresources for background on the aggregation framework and its use:

TTL Collections

TTL collections remove expired data from a collection, using a specialindex and a background thread that deletes expired documents everyminute. These collections are useful as an alternative tocapped collections in some cases, such as for datawarehousing and caching cases, including: machine generated event data,logs, and session information that needs to persist in a databasefor only a limited period of time.

For more information, see the Expire Data from Collections by Setting TTL tutorial.

Concurrency Improvements

MongoDB 2.2 increases the server’s capacity for concurrentoperations with the following improvements:

Improved Data Center Awareness with Tag Aware Sharding

MongoDB 2.2 adds additional support for geographic distribution orother custom partitioning for sharded collections in clusters. By using this “tag aware” sharding, you canautomatically ensure that data in a sharded database system is alwayson specific shards. For example, with tag aware sharding, you canensure that data is closest to the application servers that use thatdata most frequently.

Shard tagging controls data location, and is complementary butseparate from replica set tagging, which controls readpreference and write concern. For example, shard tagging can pin all“USA” data to one or more logical shards, while replica set taggingcan control which mongod instances (e.g. “production”or “reporting”) the application uses to service requests.

See the documentation for the following helpers in the mongoshell that support tagged sharding configuration:

Fully Supported Read Preference Semantics

All MongoDB clients and drivers now support full readpreferences, including consistentsupport for a full range of read preference modes and tag sets. This support extends to themongos and applies identically to single replica sets andto the replica sets for each shard in a sharded cluster.

Additional read preference support now exists in the mongoshell using the readPref() cursor method.

Compatibility Changes

Authentication Changes

MongoDB 2.2 provides more reliable and robust support forauthentication clients, including drivers and mongosinstances.

If your cluster runs with authentication:

  • For all drivers, use the latest release of your driver and checkits release notes.
  • In sharded environments,to ensure that your cluster remains available during the upgradeprocess you must use the upgrade procedure for sharded clusters.

findAndModify Returns Null Value for Upserts that Perform Inserts

In version 2.2, for upsert that perform inserts with thenew option set to false, findAndModify commands willnow return the following output:

  1. { 'ok': 1.0, 'value': null }

In the mongo shell, upsert findAndModifyoperations that perform inserts (with new set to false.)only output a null value.

In version 2.0 these operations would return an empty document,e.g. { }.

See: SERVER-6226 for more information.

mongodump 2.2 Output Incompatible with Pre-2.2 mongorestore

If you use the mongodump tool from the 2.2 distribution tocreate a dump of a database, you must use a 2.2 (or later) version ofmongorestore to restore that dump.

See: SERVER-6961 for more information.

ObjectId().toString() Returns String Literal ObjectId("…")

In version 2.2, the toString() method returns thestring representation of the ObjectId()object and has the format ObjectId("…").

Consider the following example that calls thetoString() method on theObjectId("507c7f79bcf86cd7994f6c0e") object:

  1. ObjectId("507c7f79bcf86cd7994f6c0e").toString()

The method now returns the stringObjectId("507c7f79bcf86cd7994f6c0e").

Previously, in version 2.0, the method would return the hexadecimalstring 507c7f79bcf86cd7994f6c0e.

If compatibility between versions 2.0 and 2.2 is required, useObjectId().str, which holds thehexadecimal string value in both versions.

ObjectId().valueOf() Returns hexadecimal string

In version 2.2, the valueOf() method returns thevalue of the ObjectId() object as alowercase hexadecimal string.

Consider the following example that calls the valueOf() method on theObjectId("507c7f79bcf86cd7994f6c0e") object:

  1. ObjectId("507c7f79bcf86cd7994f6c0e").valueOf()

The method now returns the hexadecimal string507c7f79bcf86cd7994f6c0e.

Previously, in version 2.0, the method would return the objectObjectId("507c7f79bcf86cd7994f6c0e").

If compatibility between versions 2.0 and 2.2 is required, useObjectId().str attribute, which holds thehexadecimal string value in both versions.

Behavioral Changes

Restrictions on Collection Names

In version 2.2, collection names cannot:

  • contain the $.
  • be an empty string (i.e. "").

This change does not affect collections created with now illegal namesin earlier versions of MongoDB.

These new restrictions are in addition to the existing restrictions oncollection names which are:

  • A collection name should begin with a letter or an underscore.
  • A collection name cannot contain the null character.
  • Begin with the system. prefix. MongoDBreserves system.for system collections, such as thesystem.indexes collection.
  • The maximum size of a collection name is 128 characters, includingthe name of the database. However, for maximum flexibility,collections should have names less than 80 characters.

Collections names may have any other valid UTF-8 string.

See the SERVER-4442 and theNaming Restrictions FAQ item.

Restrictions on Database Names for Windows

Database names running on Windows can no longer contain the followingcharacters:

  1. /\. "*<>:|?

The names of the data files include the database name. If you attemptto upgrade a database instance with one or more of these characters,mongod will refuse to start.

Change the name of these databases before upgrading. SeeSERVER-4584 and SERVER-6729 for more information.

_id Fields and Indexes on Capped Collections

All capped collections now have an idfield by default, _if they exist outside of the local database,and now have indexes on the _id field. This change only affects cappedcollections created with 2.2 instances and does not affect existingcapped collections.

See: SERVER-5516 for more information.

New $elemMatch Projection Operator

The $elemMatch operator allows applications to narrowthe data returned from queries so that the query operation will onlyreturn the first matching element in an array. See the$elemMatch reference and theSERVER-2238 and SERVER-828 issues for moreinformation.

Windows Specific Changes

Windows XP is Not Supported

As of 2.2, MongoDB does not support Windows XP. Please upgrade to amore recent version of Windows to use the latest releases ofMongoDB. See SERVER-5648 for more information.

Service Support for mongos.exe

You may now run mongos.exe instances as a WindowsService. See the mongos.exe reference andStart MongoDB Community Edition as a Windows Service and SERVER-1589 formore information.

Log Rotate Command Support

MongoDB for Windows now supports log rotation by way of thelogRotate database command. See SERVER-2612 formore information.

New Build Using SlimReadWrite Locks for Windows Concurrency

Labeled “2008+” on the Downloads Page, this build for 64-bitversions of Windows Server 2008 R2 and for Windows 7 or newer, offersincreased performance over the standard 64-bit Windows build ofMongoDB. See SERVER-3844 for more information.

Tool Improvements

Index Definitions Handled by mongodump and mongorestore

When you specify the —collectionoption to mongodump, mongodump will now backupthe definitions for all indexes that exist on the sourcedatabase. When you attempt to restore this backup withmongorestore, the target mongod will rebuild allindexes. See SERVER-808 for more information.

mongorestore now includes the —noIndexRestore option to provide the precedingbehavior. Use —noIndexRestoreto prevent mongorestore from buildingprevious indexes.

mongooplog for Replaying Oplogs

The mongooplog tool makes it possible to pull oplogentries from mongod instance and apply them to anothermongod instance. You can use mongooplog toachieve point-in-time backup of a MongoDB data set. See theSERVER-3873 case and the mongooplogreference.

Authentication Support for mongotop and mongostat

mongotop and mongostat now contain support forusername/password authentication. See SERVER-3875 andSERVER-3871 for more information regarding this change. Alsoconsider the documentation of the following options for additionalinformation:

Write Concern Support for mongoimport and mongorestore

mongoimport now provides an option to halt the import ifthe operation encounters an error, such as a network interruption, aduplicate key exception, or a write error.The —stopOnError optionwillproduce an error rather than silently continue importing data. SeeSERVER-3937 for more information.

In mongorestore, the —woption provides support for configurable write concern.

mongodump Support for Reading from Secondaries

You can now run mongodump when connected to asecondary member of a replica set. SeeSERVER-3854 for more information.

mongoimport Support for full 16MB Documents

Previously, mongoimport would only import documents thatwere less than 4 megabytes in size. This issue is now corrected, andyou may use mongoimport to import documents that are atleast 16 megabytes ins size. See SERVER-4593 for moreinformation.

Timestamp() Extended JSON format

MongoDB extended JSON now includes a new Timestamp() type torepresent the Timestamp type that MongoDB uses for timestamps in theoplog among other contexts.

This permits tools like mongooplog and mongodumpto query for specific timestamps. Consider the followingmongodump operation:

  1. mongodump --db local --collection oplog.rs --query '{"ts":{"$gt":{"$timestamp" : {"t": 1344969612000, "i": 1 }}}}'  --out oplog-dump

See SERVER-3483 for more information.

Shell Improvements

Improved Shell User Interface

2.2 includes a number of changes that improve the overall quality andconsistency of the user interface for the mongo shell:

  • Full Unicode support.
  • Bash-like line editing features. See SERVER-4312 for moreinformation.
  • Multi-line command support in shell history.See SERVER-3470 for more information.
  • Windows support for the edit command. See SERVER-3998 formore information.

Helper to load Server-Side Functions

The db.loadServerScripts() loads the contents of the currentdatabase’s system.js collection into the current mongoshell session. See SERVER-1651 for more information.

Support for Bulk Inserts

If you pass an array of documents to theinsert() method, the mongoshell will now perform a bulk insert operation. SeeSERVER-3819 and SERVER-2395 for more information.

Note

For bulk inserts on sharded clusters, the getLastErrorcommand alone is insufficient to verify success. Applicationsshould must verify the success of bulk inserts in applicationlogic.

Operations

Support for Logging to Syslog

See the SERVER-2957 case and the documentation ofthe syslogFacility run-time option or the mongod —syslogand mongos —syslog command line-options.

touch Command

Added the touch command to read the data and/or indexesfrom a collection into memory. See: SERVER-2023 andtouch for more information.

indexCounters No Longer Report Sampled Data

indexCounters now report actual counters that reflect indexuse and state. In previous versions, these data were sampled. SeeSERVER-5784 and indexCounters for more information.

Padding Specifiable on compact Command

See the documentation of the compact and theSERVER-4018 issue for more information.

Added Build Flag to Use System Libraries

The Boost library, version 1.49, is now embedded in the MongoDBcode base.

If you want to build MongoDB binaries using system Boost libraries,you can pass scons using the —use-system-boost flag, as follows:

  1. scons --use-system-boost

When building MongoDB, you can also pass scons a flag to compileMongoDB using only system libraries rather than the included versionsof the libraries. For example:

  1. scons --use-system-all

See the SERVER-3829 and SERVER-5172 issues for moreinformation.

Memory Allocator Changed to TCMalloc

To improve performance, MongoDB 2.2 uses the TCMalloc memoryallocator from Google Perftools. For more information about thischange see the SERVER-188 and SERVER-4683. For moreinformation about TCMalloc, see the documentation of TCMalloc itself.

Replication

Improved Logging for Replica Set Lag

When secondary members of a replica set fall behind inreplication, mongod now provides better reporting in thelog. This makes it possible to track replication in general andidentify what process may produce errors or halt replication. SeeSERVER-3575 for more information.

Replica Set Members can Sync from Specific Members

The new replSetSyncFrom command and newrs.syncFrom() helper in the mongo shell make itpossible for you to manually configure from which member of the set areplica will poll oplog entries. Use these commands tooverride the default selection logic if needed. Always exercisecaution with replSetSyncFrom when overriding the defaultbehavior.

Replica Set Members will not Sync from Members Without Indexes Unless buildIndexes: false

To prevent inconsistency between members of replica sets, if themember of a replica set hasbuildIndexes set to true,other members of the replica set will not sync from this member,unless they also havebuildIndexes set totrue. See SERVER-4160 for more information.

New Option To Configure Index Pre-Fetching during Replication

By default, when replicating options, secondarieswill pre-fetch Indexes associated with a query to improve replicationthroughput in most cases. The replication.secondaryIndexPrefetch setting and`—replIndexPrefetch option allow administrators to disablethis feature or allow the mongod to pre-fetch only theindex on the _id field. See SERVER-6718 for more information.

Map Reduce Improvements

In 2.2 Map Reduce received the following improvements:

Sharding Improvements

Index on Shard Keys Can Now Be a Compound Index

If your shard key uses the prefix of an existing index, then you do notneed to maintain a separate index for your shard key in addition toyour existing index. This index, however, cannot be a multi-keyindex. See the Shard Key Indexes documentation andSERVER-1506 for more information.

Migration Thresholds Modified

The migration thresholds havechanged in 2.2 to permit more even distribution of chunks in collections that have smaller quantities of data. See theMigration Thresholds documentation for moreinformation.

Licensing Changes

Added License notice for Google Perftools (TCMalloc Utility). See theLicense Noticeand the SERVER-4683 for more information.

Resources