Release Notes for MongoDB 2.2
On this page
- Upgrading
- Changes
- Compatibility Changes
- Behavioral Changes
- Windows Specific Changes
- Tool Improvements
- Shell Improvements
- Operations
- Added Build Flag to Use System Libraries
- Memory Allocator Changed to TCMalloc
- Improved Logging for Replica Set Lag
- Replica Set Members can Sync from Specific Members
- Replica Set Members will not Sync from Members Without Indexes Unless
buildIndexes: false
- New Option To Configure Index Pre-Fetching during Replication
- Index on Shard Keys Can Now Be a Compound Index
- Migration Thresholds Modified
Upgrading
MongoDB 2.2 is a production release series and succeeds the 2.0 production release series.
MongoDB 2.0 data files are compatible with 2.2-series binaries without any special migration process. However, always perform the upgrade process for replica sets 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 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 anymongod
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]
[1] | To minimize the interruption caused by
election process, always upgrade the
secondaries 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 the MongoDB Download Page.
Shutdown your
mongod
instance. Replace the existing binary with the 2.2mongod
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:
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 amongod
instance, wait for the member to recover toSECONDARY
state before upgrading the next instance. To check the member's state, issuers.status()
in themongo
shell.Use the
mongo
shell methodrs.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 ofrs.status()
, shut down the previous primary and replacemongod
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:
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.
Note
Balancing is not currently supported in mixed 2.0.x and 2.2.0 deployments. Thus you will want to reach a consistent version for all shards within a reasonable period of time, e.g. same-day. See SERVER-6902 for more information.
Changes
Major Features
Aggregation Pipeline
An aggregation pipeline makes it possible to do aggregation
operations without needing to use map-reduce. The
aggregate
command creates an aggregation pipeline, and the
aggregate()
helper in the mongo
shell
provides an interface to these operations. Consider the following
resources for background on aggregation pipelines and their use:
Documentation: Aggregation Operations
Reference: Aggregation Reference
TTL Collections
TTL collections remove expired data from a collection, using a special index and a background thread that deletes expired documents every minute. These collections are useful as an alternative to capped collections in some cases, such as for data warehousing and caching cases, including: machine generated event data, logs, and session information that needs to persist in a database for 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 concurrent operations with the following improvements:
To reflect these changes, MongoDB now provides changed and improved
reporting for concurrency and use. See locks, recordStats, db.currentOp()
,
mongotop
, and mongostat
.
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:
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.
Compatibility Changes
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.
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 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 reservessystem.
for system collections, such as thesystem.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 Specific Changes
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 mongos.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.
Tool Improvements
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.
Shell Improvements
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.
Note
For bulk inserts on sharded clusters, the getLastError
command alone is insufficient to verify success. Applications
should must verify the success of bulk inserts in application
logic.
Operations
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.
Added Build Flag to Use System Libraries
The Boost library, version 1.49, is now embedded in the MongoDB code base.
If you want to build MongoDB binaries using system Boost libraries,
you can pass scons
using the --use-system-boost
flag, as follows:
scons --use-system-boost
When building MongoDB, you can also pass scons
a flag to compile
MongoDB using only system libraries rather than the included versions
of the libraries. For example:
scons --use-system-all
See the SERVER-3829 and SERVER-5172 issues for more information.
Memory Allocator Changed to TCMalloc
To improve performance, MongoDB 2.2 uses the TCMalloc memory allocator from Google Perftools. For more information about this change see the SERVER-188 and SERVER-4683. For more information about TCMalloc, see the documentation of TCMalloc itself.
Replication
On this page
- Upgrading
- Changes
- Compatibility Changes
- Behavioral Changes
- Windows Specific Changes
- Tool Improvements
- Shell Improvements
- Operations
- Added Build Flag to Use System Libraries
- Memory Allocator Changed to TCMalloc
- Improved Logging for Replica Set Lag
- Replica Set Members can Sync from Specific Members
- Replica Set Members will not Sync from Members Without Indexes Unless
buildIndexes: false
- New Option To Configure Index Pre-Fetching during Replication
- Index on Shard Keys Can Now Be a Compound Index
- Migration Thresholds Modified
Improved Logging for Replica Set Lag
When secondary members of a replica set fall behind in
replication, mongod
now provides better reporting in the
log. This makes it possible to track replication in general and
identify what process may produce errors or halt replication. See
SERVER-3575 for more information.
Replica Set Members can Sync from Specific Members
The new replSetSyncFrom
command and new
rs.syncFrom()
helper in the mongo
shell make it
possible for you to manually configure from which member of the set a
replica will poll oplog entries. Use these commands to
override the default selection logic if needed. Always exercise
caution with replSetSyncFrom
when overriding the default
behavior.
Replica Set Members will not Sync from Members Without Indexes Unless buildIndexes: false
To prevent inconsistency between members of replica sets, if the
member of a replica set has
buildIndexes
set to true
,
other members of the replica set will not sync from this member,
unless they also have
buildIndexes
set to true
. See
SERVER-4160 for more information.
New Option To Configure Index Pre-Fetching during Replication
By default, when replicating options, secondaries
will pre-fetch Indexes associated with a query to improve replication
throughput in most cases. The replication.secondaryIndexPrefetch
setting and
`--replIndexPrefetch
option allow administrators to disable
this feature or allow the mongod
to pre-fetch only the
index on the _id
field. See SERVER-6718 for more information.
Map Reduce Improvements
On this page
- Upgrading
- Changes
- Compatibility Changes
- Behavioral Changes
- Windows Specific Changes
- Tool Improvements
- Shell Improvements
- Operations
- Added Build Flag to Use System Libraries
- Memory Allocator Changed to TCMalloc
- Improved Logging for Replica Set Lag
- Replica Set Members can Sync from Specific Members
- Replica Set Members will not Sync from Members Without Indexes Unless
buildIndexes: false
- New Option To Configure Index Pre-Fetching during Replication
- Index on Shard Keys Can Now Be a Compound Index
- Migration Thresholds Modified
In 2.2 Map Reduce received the following improvements:
Sharding Improvements
On this page
- Upgrading
- Changes
- Compatibility Changes
- Behavioral Changes
- Windows Specific Changes
- Tool Improvements
- Shell Improvements
- Operations
- Added Build Flag to Use System Libraries
- Memory Allocator Changed to TCMalloc
- Improved Logging for Replica Set Lag
- Replica Set Members can Sync from Specific Members
- Replica Set Members will not Sync from Members Without Indexes Unless
buildIndexes: false
- New Option To Configure Index Pre-Fetching during Replication
- Index on Shard Keys Can Now Be a Compound Index
- Migration Thresholds Modified
Index on Shard Keys Can Now Be a Compound Index
If your shard key uses the prefix of an existing index, then you do not need to maintain a separate index for your shard key in addition to your existing index. This index, however, cannot be a multi-key index. See the Shard Key Indexes documentation and SERVER-1506 for more information.
Migration Thresholds Modified
The migration thresholds have changed in 2.2 to permit more even distribution of chunks in collections that have smaller quantities of data. See the Migration Thresholds documentation for more information.
Licensing Changes
On this page
- Upgrading
- Changes
- Compatibility Changes
- Behavioral Changes
- Windows Specific Changes
- Tool Improvements
- Shell Improvements
- Operations
- Added Build Flag to Use System Libraries
- Memory Allocator Changed to TCMalloc
- Improved Logging for Replica Set Lag
- Replica Set Members can Sync from Specific Members
- Replica Set Members will not Sync from Members Without Indexes Unless
buildIndexes: false
- New Option To Configure Index Pre-Fetching during Replication
- Index on Shard Keys Can Now Be a Compound Index
- Migration Thresholds Modified
Added License notice for Google Perftools (TCMalloc Utility). See the License Notice and the SERVER-4683 for more information.
Resources
On this page
- Upgrading
- Changes
- Compatibility Changes
- Behavioral Changes
- Windows Specific Changes
- Tool Improvements
- Shell Improvements
- Operations
- Added Build Flag to Use System Libraries
- Memory Allocator Changed to TCMalloc
- Improved Logging for Replica Set Lag
- Replica Set Members can Sync from Specific Members
- Replica Set Members will not Sync from Members Without Indexes Unless
buildIndexes: false
- New Option To Configure Index Pre-Fetching during Replication
- Index on Shard Keys Can Now Be a Compound Index
- Migration Thresholds Modified