MongoDB utilities

The ObjectRocket platform is compatible with almost any of the standard MongoDB utilities. The following examples show how to use the most common MongoDB utilities.

mongodump

mongodump creates a binary export of your mongodb instance. When run against a sharded instance, it’s routed through a mongos, or directly from the primary when using a replica set.

The following recommendations are for using mongodump:

  • Verify connectivity to the instance (ACLs and so on).
  • Match the version of mongodump with your instance by running mongodump --version.
  • Verify the user has the necessary privileges and roles to perform a backup if you’re not on ObjectRocket.
  • Specify the location for the output by using the -o flag.

Note

If you don’t specify a location when running mongodump, it creates a folder named dump in your current directory and overwrites anything currently existing in the dump/ folder.

The following is an example of basic usage, backing up from the host iad-mongos2.objectrocket.com, on port 12345, from the database example with the username example_user, to the folder named backup using -o:

$ mongodump --host iad-mongos2.objectrocket.com:12345 -d example_db -u example_user -p -o backup

Below are some other common flags:

  • Backup a single collection within a database by using -c
$ mongodump --host iad-mongos2.objectrocket.com:12345 -d example_db -c coll_example -u example_user -p -o backup
  • Backup documents returned by a particular query by using -q
$ mongodump --host iad-mongos2.objectrocket.com:12345 -u example_user -p -d example_db -q '{ _id : { $gte : ObjectId("50ad7bce1a3e927d690385ec") } }'

Note

When using -q wrap the json query in single quotes, (e.g. ') so it doesn’t interact with your shell. Sometimes escaping is necessary depending on the query.

The backup directory includes .json and .bson files. The .bson files are binary data, and the .json files contain metadata. You can compress the backups as expected by using gzip or any preferred method. Both bson and json files are necessary to perform restores, so be sure to include those in your compressed files.

mongorestore

mongorestore writes data from a backup created by mongodump to a mongodb instance. mongorestore can create a new database or add data to an existing database.

The example below restores to the host syd-mongos0.objectrocket.com, on port 12345, to the database usda, using the yoda user, from the backup folder of dump/usda/. This restores everything in that folder to the specified database. You should always match the binary you’re using with the version you’re restoring to.

$ mongorestore --host syd-mongos0.objectrocket.com:12345 -d usda -u yoda -p dump/usda/
2015-08-12T08:41:06.330-0700 building a list of collections to restore from dump/usda/ dir
2015-08-12T08:41:06.637-0700 reading metadata file from dump/usda/nutrition.metadata.json
2015-08-12T08:41:06.637-0700 restoring usda.nutrition from file dump/usda/nutrition.bson
2015-08-12T08:41:09.330-0700 [############............] usda.nutrition 32.0
2015-08-12T08:41:45.330-0700 [########################] usda.nutrition 62.2 MB/62.2 MB (100.0%)
2015-08-12T08:41:45.895-0700 restoring indexes for collection usda.nutrition from metadata
2015-08-12T08:41:46.359-0700 finished restoring usda.nutrition 2015-08-12T08:41:46.359-0700 done

Warning

mongorestore won’t overwrite or update existing documents unless replaying oplog events, it only inserts. Any insertion failures are logged to the target logs, not to STDOUT.

Here are the common flags used with mongorestore:

  • --drop drops the collection you’re attempting to restore before any inserts.
  • --noIndexRestore won’t restore indexes found in the metadata json files.
  • --stopOnError stops restoring upon an error, instead of continuing silently.

mongoexport

mongoexport exports your data to CSV, TSV, or JSON files, which are more human readable and compatible with more applications.

. . note

Unlike ``mongodump``, you can't export an entire database and must specify a collection.

This example uses the host hkg-mongos0.objectrocket.com, the port 12345, the database zips, the collection zips, and outputs to a JSON file zips.json.

$ mongoexport --host hkg-mongos0.objectrocket.com:12345 -d zips -c zips -u USER -p PASSWORD --type json -o zips.json
  • When using --type, you must specify either json or csv. json is the default when you don’t specify a type. You should use“csv“ in conjunction with --fields or the --fieldFile option to specify the fields to export from the collection.

The following example uses csv and --fields:

$ mongoexport --host hkg-mongos0.objectrocket.com:12345 -d zips -c zips -u USER -p PASSWORD --type csv --fields name,address -o zips.csv

Similar to mongodump and mongorestore, you’re able to specify queries for your export by using the -q argument.

$ mongoexport --host hkg-mongos0.objectrocket.com:12345 -d zips -c zips -u USER -p PASSWORD -q '{ zips : { $gt : 60000 } }' -o zips.json

mongoimport

mongoimport is the opposite of mongoexport, and ingests json or csv into MongoDB.

The following example imports zips.json into the hkg-mongos0.objectrocket.com host, by using the 12345 port, and the zips database and collection.

$ mongoimport --host hkg-mongos0.objectrocket.com:12345 -d zips -c zips -u USER -p PASSWORD --file zips.json

If the database and collection don’t exist on the host you’re importing to, mongoimport creates them, similar to mongorestore.

Here are some important flags to be aware of when using mongoimport:

  • --fields must be used when importing csv that do not include the field names in the header of the file.
  • --ignoreBlanks ignores empty fields in csv or tsv imports. If not specified, mongoimport creates fields without values in those documents.
  • --drop drops the collection you’re inserting to before it begins the import.
  • --stopOnError stops the import upon the first error rather than continuing.
  • --upsert updates existing documents if they match an imported document.
  • --upsertFields lets you specify what to match when using --upsert. The default match, when not specified, uses _id.
  • --writeConcern lets you specify what writeConcern to use when importing. The normal writeConcern options apply here.