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``: .. code-block:: bash $ 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`` .. code-block:: bash $ 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`` .. code-block:: bash $ 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. .. code-block:: bash $ 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``. .. code-block:: bash $ 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``: .. code-block:: bash $ 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. .. code-block:: bash $ 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. .. code-block:: bash $ 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.