Synopsis

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

• Check your driver documentation for information regarding required compatibility upgrades, and always run the recent release of your driver.

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

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

• For all upgrades of sharded clusters:

  • turn off the balancer during the upgrade process. See the Disable the Balancer section for more information.

  • upgrade all mongos instances before upgrading any mongod instances.

Other than the above restrictions, 2.2 processes can interoperate with 2.0 and 1.8 tools and processes. You can safely upgrade the mongod and mongos components of a deployment one by one while the deployment is otherwise operational. Be sure to read the detailed upgrade procedures below before upgrading production systems. [1]

Upgrading a Standalone mongod

1. Download binaries of the latest release in the 2.2 series from the MongoDB Download Page.

2. Shutdown your mongod instance. Replace the existing binary 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 the other members are available to minimize downtime. Use the following procedure:

1. Upgrade the secondary members of the set one at a time by shutting down the mongod and replacing the 2.0 binary with the 2.2 binary. After upgrading a mongod instance, wait for the member to recover to SECONDARY state before upgrading the next instance. To check the member's state, issue rs.status() in the mongo shell.

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

   Once the primary has stepped down and another member has assumed PRIMARY state, as observed in the output of rs.status(), shut down the previous primary and replace mongod binary with the 2.2 binary and start the new process.

   Note

   Replica set failover is not instant but will render the set unavailable to read or accept writes until the failover process completes. Typically this takes 10 seconds or more. You may wish to plan the upgrade during a predefined maintenance window.

Upgrading a Sharded Cluster

Use the following procedure to upgrade a sharded cluster:

• Disable the balancer.

• Upgrade all mongos instances first, in any order.

• Upgrade all of the mongod config server instances using the stand alone procedure. To keep the cluster online, be sure that at all times at least one config server is up.

• Upgrade each shard's replica set, using the upgrade procedure for replica sets detailed above.

• re-enable the balancer.

Major Features

Improved Data Center Awareness with Tag Aware Sharding

MongoDB 2.2 adds additional support for geographic distribution or other custom partitioning for sharded collections in clusters. By using this "tag aware" sharding, you can automatically ensure that data in a sharded database system is always on specific shards. For example, with tag aware sharding, you can ensure that data is closest to the application servers that use that data most frequently.

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

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

• sh.addShardTag()

• sh.addTagRange()

• sh.removeShardTag()

Fully Supported Read Preference Semantics

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

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

Authentication Changes

MongoDB 2.2 provides more reliable and robust support for authentication clients, including drivers and mongos instances.

If your cluster runs with authentication:

• For all drivers, use the latest release of your driver and check its release notes.

• In sharded environments, to ensure that your cluster remains available during the upgrade process 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 the new option set to false, findAndModify commands will now return the following output:

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

In the mongo shell, upsert findAndModify operations 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 to create a dump of a database, you must use a 2.2 (or later) version of mongorestore to restore that dump.

See: SERVER-6961 for more information.

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

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

Consider the following example that calls the toString() method on the ObjectId("507c7f79bcf86cd7994f6c0e") object:

ObjectId("507c7f79bcf86cd7994f6c0e").toString()

The method now returns the string ObjectId("507c7f79bcf86cd7994f6c0e").

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

If compatibility between versions 2.0 and 2.2 is required, use ObjectId().str, which holds the hexadecimal string value in both versions.

ObjectId().valueOf() Returns hexadecimal string

In version 2.2, the valueOf() method returns the value of the ObjectId() object as a lowercase hexadecimal string.

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

ObjectId("507c7f79bcf86cd7994f6c0e").valueOf()

The method now returns the hexadecimal string 507c7f79bcf86cd7994f6c0e.

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

If compatibility between versions 2.0 and 2.2 is required, use ObjectId().str attribute, which holds the hexadecimal string value in both versions.

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 names in earlier versions of MongoDB.

These new restrictions are in addition to the existing restrictions on collection 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. MongoDB reserves system. for system collections, such as the system.indexes collection.

• The maximum size of a collection name is 128 characters, including the 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 the Naming Restrictions FAQ item.

Restrictions on Database Names for Windows

Database names running on Windows can no longer contain the following characters:

/\. "*<>:|?

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

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

_id Fields and Indexes on Capped Collections

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

See: SERVER-5516 for more information.

New $elemMatch Projection Operator

The $elemMatch operator allows applications to narrow the data returned from queries so that the query operation will only return the first matching element in an array. See the $elemMatch reference and the SERVER-2238 and SERVER-828 issues for more information.

Windows XP is Not Supported

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

Service Support for mongos.exe

You may now run exe instances as a Windows Service.

Log Rotate Command Support

MongoDB for Windows now supports log rotation by way of the logRotate database command. See SERVER-2612 for more information.

New Build Using SlimReadWrite Locks for Windows Concurrency

Labeled "2008+" on the Downloads Page, this build for 64-bit versions of Windows Server 2008 R2 and for Windows 7 or newer, offers increased performance over the standard 64-bit Windows build of MongoDB. See SERVER-3844 for more information.

Index Definitions Handled by mongodump and mongorestore

When you specify the --collection option to mongodump, mongodump will now backup the definitions for all indexes that exist on the source database. When you attempt to restore this backup with mongorestore, the target mongod will rebuild all indexes. See SERVER-808 for more information.

mongorestore now includes the --noIndexRestore option to provide the preceding behavior. Use --noIndexRestore to prevent mongorestore from building previous indexes.

mongooplog for Replaying Oplogs

The mongooplog tool makes it possible to pull oplog entries from mongod instance and apply them to another mongod instance. You can use mongooplog to achieve point-in-time backup of a MongoDB data set. See the SERVER-3873 case and the mongooplog reference.

Authentication Support for mongotop and mongostat

mongotop and mongostat now contain support for username/password authentication. See SERVER-3875 and SERVER-3871 for more information regarding this change. Also consider the documentation of the following options for additional information:

• mongotop --username

• mongotop --password

• mongostat --username

• mongostat --password

Write Concern Support for mongoimport and mongorestore

mongoimport now provides an option to halt the import if the operation encounters an error, such as a network interruption, a duplicate key exception, or a write error. The --stopOnError option will produce an error rather than silently continue importing data. See SERVER-3937 for more information.

In mongorestore, the --w option provides support for configurable write concern.

mongodump Support for Reading from Secondaries

You can now run mongodump when connected to a secondary member of a replica set. See SERVER-3854 for more information.

mongoimport Support for full 16MB Documents

Previously, mongoimport would only import documents that were less than 4 megabytes in size. This issue is now corrected, and you may use mongoimport to import documents that are at least 16 megabytes ins size. See SERVER-4593 for more information.

Timestamp() Extended JSON format

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

This permits tools like mongooplog and mongodump to query for specific timestamps. Consider the following mongodump operation:

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

See SERVER-3483 for more information.

Improved Shell User Interface

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

• Full Unicode support.

• Bash-like line editing features. See SERVER-4312 for more information.

• Multi-line command support in shell history. See SERVER-3470 for more information.

• Windows support for the edit command. See SERVER-3998 for more information.

Helper to load Server-Side Functions

The db.loadServerScripts() method loads the contents of the current database's system.js collection into the current mongo shell session. See SERVER-1651 for more information.

Support for Bulk Inserts

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

Support for Logging to Syslog

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

touch Command

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

indexCounters No Longer Report Sampled Data

indexCounters now report actual counters that reflect index use and state. In previous versions, these data were sampled. See SERVER-5784 and indexCounters for more information.

Padding Specifiable on compact Command

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