From 5ed49e01ae842b4b7169be12dabd57ddcb8f5852 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 26 Mar 2013 15:06:33 -0400 Subject: [PATCH] DOCS-1217 mongorestore examples --- source/reference/mongorestore.txt | 32 +++-- ...p-databases-with-binary-database-dumps.txt | 114 ++++++++++++++---- 2 files changed, 110 insertions(+), 36 deletions(-) diff --git a/source/reference/mongorestore.txt b/source/reference/mongorestore.txt index 5c18bfd8ed1..b113cd01199 100644 --- a/source/reference/mongorestore.txt +++ b/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 ` 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 ` 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 , -p 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 ` + 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 , -d @@ -186,7 +192,8 @@ Options Limits the documents that :program:`mongorestore` imports to only those documents that match the JSON document specified as ``''``. 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 diff --git a/source/tutorial/backup-databases-with-binary-database-dumps.txt b/source/tutorial/backup-databases-with-binary-database-dumps.txt index 9e64ac694fa..2e325bda167 100644 --- a/source/tutorial/backup-databases-with-binary-database-dumps.txt +++ b/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 ` and :option:`--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 ` and :option:`--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 -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 ` and :option:`--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 -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 ` and :option:`--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. \ No newline at end of file