DOCS-1217 mongorestore examples

source/reference/mongorestore.txt

@@ -11,7 +11,7 @@ Synopsis
 --------
 
 The :program:`mongorestore` tool imports content from binary database
-dump, created by :program:`mongodump` into a specific
+dump, created by :program:`mongodump`, into a specific
 database. :program:`mongorestore` can import content to an existing
 database or create a new one.
 
@@ -62,7 +62,8 @@ Options
    Specifies a resolvable hostname for the :program:`mongod` to which
    you want to restore the database. By default
    :program:`mongorestore` will attempt to connect to a MongoDB
-   process running on the localhost port number ``27017``.
+   process running on the localhost port number ``27017``. For an
+   example of :option:`--host`, see :ref:`backup-restore-dump`.
 
    Optionally, specify a port number to connect a MongoDB instance
    running on a port other than ``27017``.
@@ -73,7 +74,8 @@ Options
 
    Specifies the port number, if the MongoDB instance is not running
    on the standard port (i.e. ``27017``). You may also specify a port
-   number using the :option:`--host <mongorestore --host>` command.
+   number using the :option:`--host` command. For
+   an example of :option:`--port`, see :ref:`backup-restore-dump`.
 
 .. option:: --ipv6
 
@@ -93,16 +95,18 @@ Options
 
    Specifies a username to authenticate to the MongoDB instance, if
    your database requires authentication. Use in conjunction with the
-   :option:`--password <mongorestore --password>` option to supply a
-   password.
+   :option:`--password` option to supply a
+   password. For an example of :option:`--username`, see
+   :ref:`backup-restore-dump`.
 
 .. option:: --password <password>, -p <password>
 
    Specifies a password to authenticate to the MongoDB instance. Use
-   in conjunction with the :option:`mongorestore --username` option to
-   supply a username.
+   in conjunction with the :option:`--username` option to
+   supply a username. For an example of :option:`--password`, see
+   :ref:`backup-restore-dump`.
 
-   If you specify a :option:`--username <mongorestore --username>`
+   If you specify a :option:`--username`
    without the :option:`--password` option, :program:`mongorestore`
    will prompt for a password interactively.
 
@@ -117,7 +121,8 @@ Options
    :program:`mongod`. To run with :option:`--dbpath`,
    :program:`mongorestore` needs to lock access to the data directory:
    as a result, no :program:`mongod` can access the same path while the
-   process runs.
+   process runs. For an example of :option:`--dbpath`, see
+   :ref:`backup-restore-dbpath`.
 
 .. option:: --directoryperdb
 
@@ -133,7 +138,8 @@ Options
    Allows :program:`mongorestore` write to the durability
    :term:`journal` to ensure that the data files will remain in a
    consistent state during the write process. This option is only
-   relevant when specifying the :option:`--dbpath` option.
+   relevant when specifying the :option:`--dbpath` option. For an
+   example of :option:`--journal`, see :ref:`backup-restore-dbpath`.
 
 .. option:: --db <db>, -d <db>
 
@@ -186,7 +192,8 @@ Options
    Limits the documents that :program:`mongorestore` imports to only
    those documents that match the JSON document specified as
    ``'<JSON>'``. Be sure to include the document in single quotes to
-   avoid interaction with your system's shell environment.
+   avoid interaction with your system's shell environment. For an
+   example of :option:`--filter`, see :ref:`backup-restore-filter`.
 
 .. option:: --drop
 
@@ -198,7 +205,8 @@ Options
 
    Replays the :term:`oplog` after restoring the dump to ensure that the current
    state of the database reflects the point-in-time backup captured with
-   the ":option:`mongodump --oplog`" command.
+   the ":option:`mongodump --oplog`" command. For an example of
+   :option:`--oplogReplay`, see :ref:`backup-restore-oplogreplay`.
 
 .. option:: --keepIndexVersion
 

source/tutorial/backup-databases-with-binary-database-dumps.txt

@@ -25,14 +25,28 @@ Backup a Database with ``mongodump``
 Basic ``mongodump`` Operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :program:`mongodump` utility can perform a live backup of data or
-can work against an inactive set of database files.
-The :program:`mongodump` utility can create a dump for an entire
-server/database/collection (or part of a collection using of query),
-even when the database is running and active. If you run
-:program:`mongodump` without any arguments, the command connects to
-the local database instance (e.g. ``127.0.0.1`` or ``localhost``) and
-creates a database backup named ``dump/`` in the current directory.
+The :program:`mongodump` utility can back up data by either:
+
+- connecting to a running :program:`mongod` or
+  :program:`mongos` instance, or
+
+- accessing data files without an active instance.
+
+The utility can create a backup for an entire server, database or collection,
+or can use a query to backup just part of a collection.
+
+When you run :program:`mongodump` without any arguments, the command
+connects to the local database instance (e.g. ``127.0.0.1`` or
+``localhost``) on port ``27017`` and creates a database backup named
+``dump/`` in the current directory.
+
+To backup data from a :program:`mongod` or :program:`mongos` instance
+running on the same machine and on the default port of ``27017``, simply
+issue the following:
+
+.. code-block:: sh
+
+   mongodump
 
 .. include:: /includes/note-mongodump-compatibility-2.2.rst
 
@@ -41,6 +55,18 @@ specify :option:`--db <mongodump --db>` and
 :option:`--collection <mongodump --collection>` as options to the
 :program:`mongodump` command. For example:
 
+.. code-block:: sh
+
+   mongodump --dbpath /data/db/ --out /data/backup/
+
+.. code-block:: sh
+
+   mongodump --host mongodb.example.net --port 27017
+
+:program:`mongodump` will write :term:`BSON` files that hold a copy of
+data accessible via the :program:`mongod` listening on port ``27017`` of
+the ``mongodb.example.net`` host.
+
 .. code-block:: sh
 
    mongodump --collection collection --db test
@@ -84,12 +110,12 @@ Create Backups from Non-Local ``mongod`` Instances
 
 The :option:`--host <mongodump --host>` and
 :option:`--port <mongodump --port>` options for
-:program:`mongodump` allow you to specify a non-local host to connect
-to capture the dump. Consider the following example:
+:program:`mongodump` allow you to connect to and backup from a remote host.
+Consider the following example:
 
 .. code-block:: sh
 
-   mongodump --host mongodb1.example.net --port 3017 --username user --password pass --out /opt/backup/mongodump-2011-10-24
+   mongodump --host mongodb1.example.net --port 3017 --username user --password pass --out /opt/backup/mongodump-2012-10-24
 
 On any :program:`mongodump` command you may, as above, specify username
 and password credentials to specify database authentication.
@@ -100,27 +126,45 @@ Restore a Database with ``mongorestore``
 ----------------------------------------
 
 The :program:`mongorestore` utility restores a binary backup created by
-:program:`mongodump`. Consider the following example command:
+:program:`mongodump`. By default, :program:`mongorestore` looks for a
+database backup in the :file:`dump/` directory.
+
+The :program:`mongorestore` utility can restore data either by:
+
+- connecting to a running :program:`mongod` or
+  :program:`mongos` directly, or
+
+- writing to a local database path without use of a running :program:`mongod`.
+
+The :program:`mongorestore` utility can restore either an entire
+database backup or a subset of the backup.
+
+A :program:`mongorestore` command that connects to an active
+:program:`mongod` or :program:`mongos` has the following prototype form:
 
 .. code-block:: sh
 
-   mongorestore dump-2011-10-25/
+   mongorestore --port <port number> <path to the backup>
 
-Here, :program:`mongorestore` imports the database backup located in
-the :file:`dump-2011-10-25` directory to the :program:`mongod` instance
-running on the localhost interface. By default, :program:`mongorestore`
-looks for a database dump in the :file:`dump/` directory and restores
-that. If you wish to restore to a non-default host, the
-:option:`--host <mongorestore --host>` and :option:`--port <mongorestore --port>`
-options allow you to specify a non-local host to connect to capture
-the dump. Consider the following example:
+A :program:`mongorestore` command that writes to data files
+without using a running :program:`mongod` has the following prototype
+form:
 
 .. code-block:: sh
 
-   mongorestore --host mongodb1.example.net --port 3017 --username user --password pass /opt/backup/mongodump-2011-10-24
+   mongorestore --dbpath <local database path> <path to the backup>
 
-On any :program:`mongorestore` command you may specify
-username and password credentials, as above.
+Consider the following example:
+
+.. code-block:: sh
+
+   mongorestore dump-2012-10-25/
+
+Here, :program:`mongorestore` imports the database backup in
+the :file:`dump-2012-10-25` directory to the :program:`mongod` instance
+running on the localhost interface.
+
+.. _backup-restore-oplogreplay:
 
 Restore Point in Time Oplog Backup
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -141,6 +185,8 @@ database, or you may consider the :option:`mongorestore --drop` option to drop e
 collection from the database before restoring from
 backups.
 
+.. _backup-restore-filter:
+
 Restore a Subset of data from a Binary Database Dump
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -158,6 +204,8 @@ field name ``field`` that holds a value of ``1``. Enclose the
 filter in single quotes (e.g. ``'``) to prevent the filter from
 interacting with your shell environment.
 
+.. _backup-restore-dbpath:
+
 Restore without a Running ``mongod``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -178,3 +226,21 @@ operation.
 
 .. seealso:: :doc:`/reference/mongodump` and
    :doc:`/reference/mongorestore`.
+
+Restore Backups to Non-Local ``mongod`` Instances
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, :program:`mongorestore` connects to a MongoDB instance
+running on the localhost interface (e.g. ``127.0.0.1``) and on the
+default port (``27017``). If you want to restore to a different host or
+port, use the :option:`--host <mongorestore --host>` and :option:`--port
+<mongorestore --port>` options.
+
+Consider the following example:
+
+.. code-block:: sh
+
+   mongorestore --host mongodb1.example.net --port 3017 --username user --password pass /opt/backup/mongodump-2012-10-24
+
+As above, you may specify username and password connections if your
+:program:`mongod` requires authentication.