Navigation
This version of the documentation is archived and no longer supported.

db.upgradeCheck()

Definition

db.upgradeCheck(<document>)

New in version 2.6.

Performs a preliminary check for upgrade preparedness to 2.6. The helper, available in the 2.6 mongo shell, can run connected to either a 2.4 or a 2.6 server.

The method checks for:

The method can accept a document parameter which determine the scope of the check:

Parameter Type Description
scope document

Optional. Document to limit the scope of the check to the specified collection in the database.

Omit to perform the check on all collections in the database.

The optional scope document has the following form:

{
   collection: <string>
}

Additional 2.6 changes that affect compatibility with older versions require manual checks and intervention. See Compatibility Changes in MongoDB 2.6 for details.

Behavior

db.upgradeCheck() performs collection scans and has an impact on performance. To mitigate the performance impact:

  • For sharded clusters, configure to read from secondaries and run the command on the mongos.
  • For replica sets, run the command on the secondary members.

db.upgradeCheck() can miss new data during the check when run on a live system with active write operations.

For index validation, db.upgradeCheck() only supports the check of version 1 indexes and skips the check of version 0 indexes.

The db.upgradeCheck() checks all of the data stored in the mongod instance: the time to run db.upgradeCheck() depends on the quantity of data stored by mongod.

Required Access

On systems running with authorization, a user must have access that includes the find action on all collections, including the system collections.

Example

The following example connects to a secondary running on localhost and runs db.upgradeCheck() against the employees collection in the records database. Because the output from the method can be quite large, the example pipes the output to a file.

./mongo --eval "db.getMongo().setSlaveOk(); db.upgradeCheck( { collection: 'employees' } )"  localhost/records | tee /tmp/upgradecheck.txt

Error Output

The upgrade check can return the following errors when it encounters incompatibilities in your data:

Index Key Exceed Limit

Document Error: key for index '<indexName>' (<indexSpec>) too long on document: <doc>

To resolve, remove the document. Ensure that the query to remove the document does not specify a condition on the invalid field or field.

Documents with Illegal Field Names

Document Error: document is no longer valid in 2.6 because <errmsg>: <doc>

To resolve, remove the document and re-insert with the appropriate corrections.

Index Specification Invalid

Index Error: invalid index spec for index '<indexName>': <indexSpec>

To resolve, remove the invalid index and recreate with a valid index specification.

Missing _id Index

Collection Error: lack of _id index on collection: <collectionName>

To resolve, create a unique index on _id.

Warning Output

Warning: upgradeCheck only supports V1 indexes. Skipping index: <indexSpec>

To resolve, remove the invalid index and recreate the index omitting the version specification, or reindex the collection. Reindex operation may be expensive for collections that have a large amount of data and/or a large number of indexes.