DOCSP-33862-mongorestore-example

source/mongodump.txt

@@ -627,17 +627,27 @@ Options
    Creates a file named :file:`oplog.bson` as part of the
    ``mongodump`` output. The ``oplog.bson`` file, located in
    the top level of the output directory, contains oplog entries that
-   occur during the ``mongodump`` operation. This file provides
-   an effective point-in-time snapshot of the state of a
-   ``mongod`` instance. To restore to a specific point-in-time
-   backup, use the output created with this option in conjunction with
-   :option:`mongorestore --oplogReplay`.
+   occur during the ``mongodump`` operation.
+
+   The ``oplog.bson`` file is a snapshot of the data at the time the
+   file was created. To restore the data as it was when the
+   ``oplog.bson``  file was created, use :option:`mongorestore
+   --oplogReplay`. You cannot use
+   ``mongorestore`` to restore data to any other time. For example, you
+   cannot specify a request to restore data from two days ago.
 
    Without ``--oplog``, if there are write operations during the dump
    operation, the dump will not reflect a single moment in time. Changes
    made to the database during the update process can affect the output of
    the backup.
 
+   To create a consistent ``oplog.bson`` file, pause writes on the
+   cluster. If you use ``--oplog`` to dump an individual shard's data
+   without pausing writes, the ``oplog.bson`` file will be inconsistent.
+
+   For complete tutorial to back up sharded clusters, see
+   :ref:`backup-sharded-dumps`.
+
    .. important::
 
       A ``mongodump`` running with ``--oplog`` fails if
@@ -648,11 +658,6 @@ Options
       - :method:`db.collection.renameCollection()`
       - :method:`db.collection.aggregate()` with :pipeline:`$out`
 
-   ``--oplog`` has no effect when running ``mongodump``
-   against a ``mongos`` instance to dump the entire contents of a
-   sharded cluster. However, you can use ``--oplog`` to dump
-   individual shards.
-
    ``--oplog`` only works against nodes that maintain an
    :term:`oplog`. This includes all members of a replica set.
 
@@ -729,6 +734,8 @@ For more information about ``mongodump``, see:
 - :ref:`mongodump-behavior`
 - :ref:`mongodump-examples`
 
+For a tutorial, see :ref:`backup-sharded-dumps`.
+
 .. include:: /includes/extracts/ssl-facts-see-more.rst
 
 .. toctree::

source/mongorestore.txt

@@ -551,11 +551,13 @@ Options
 .. option:: --oplogReplay
 
    After restoring the database dump, replays the :term:`oplog` entries
-   from a bson file.
+   from an ``oplog.bson`` file.
    When used in conjunction with :option:`mongodump --oplog`,
    :binary:`mongorestore --oplogReplay <~bin.mongorestore>`
-   restores the database to the point-in-time backup captured with the
-   ``mongodump --oplog`` command. 
+   restores the database to the time the ``oplog.bson`` file was created
+   with the ``mongodump --oplog`` command. You cannot use
+   ``mongorestore`` to restore data to any other time. For example, you
+   cannot specify a request to restore data from two days ago.
 
    ``mongorestore`` searches for any valid source  for the bson file
    in the following locations:
@@ -623,6 +625,11 @@ Options
    ``<time_t>`` is the seconds since the UNIX epoch, and ``<ordinal>``
    represents a counter of operations in the oplog that occurred in the
    specified second.
+
+   .. warning::
+
+      ``oplogLimit`` might cause corruption and inconsistencies in the
+      restored data.
 
    You must use :option:`--oplogLimit` in conjunction with the
    :option:`--oplogReplay` option.
@@ -637,7 +644,11 @@ Options
    file at the top level of the dump directory, ``mongorestore`` returns an 
    error.
 
+   .. warning::
 
+      ``oplogFile`` might cause corruption and inconsistencies in the
+      restored data.
+
 .. option:: --convertLegacyIndexes
 
    .. versionadded:: 100.0.0
@@ -857,6 +868,7 @@ Learn More
 - :ref:`mongorestore-compatibility-and-installation`
 - :ref:`Behavior <mongorestore-behavior-access-usage>`
 - :ref:`mongorestore-examples`
+- :ref:`backup-sharded-dumps`
 
 .. toctree::
    :maxdepth: 1

source/mongorestore/mongorestore-examples.txt

@@ -60,7 +60,7 @@ To restore a specific collection, use :option:`--nsInclude
 <mongorestore --nsInclude>`, passing in the full namespace
 (``<database>.<collection>``) of the collection.
 
-For example, the following restores the collection named
+The following example restores the collection named
 ``purchaseorders`` in the database ``test`` from the corresponding
 files located in the ``dump/`` directory.
 
@@ -345,14 +345,30 @@ namespace:
        You cannot restore the ``system.buckets.weather.bson`` file
        by itself. Attempting to do so results in an error.
 
+Use mongorestore --oplogReplay and mongodump --oplog 
+----------------------------------------------------
+
+To back up a database to an :term:`oplog` ``oplog.bson`` file, use
+:option:`mongodump --oplog`. To restore the database with an
+``oplog.bson`` file, use :option:`mongorestore --oplogReplay`. For more
+details, see :ref:`backup-restore-oplogreplay`.
+
+You can only use ``mongorestore`` to restore data as it was when the
+``oplog.bson`` file was created. You cannot use ``mongorestore`` to
+restore data to any other time. For example, you cannot specify a
+request to restore data from two days ago.
+
+For more information, see :option:`mongodump --oplog`. For a tutorial,
+see :ref:`backup-sharded-dumps`.
+
 .. _mongorestore-example-connect-using-aws-iam:
 
 Connect to a MongoDB Atlas Cluster using AWS IAM Credentials
 ------------------------------------------------------------
 
 .. versionadded:: 100.1.0
 
-To connect to a :atlas:`MongoDB Atlas <?tck=docs_server>` cluster which
+To connect to a :atlas:`MongoDB Atlas <?tck=docs_server>` cluster that
 has been configured to support authentication via `AWS IAM credentials
 <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html>`__,
 provide a :option:`connection string <mongorestore --uri>` to
@@ -401,7 +417,7 @@ use the ``MONGODB-AWS``
 - ``AWS_SESSION_TOKEN``
 
 If set, these credentials do not need to be specified in the connection
-string or via their explicit options.
+string or through their explicit options.
 
 .. note::
 
@@ -444,4 +460,6 @@ Learn More
 
 - :ref:`mongorestore`
 - :ref:`mongorestore-compatibility-and-installation`
-- :ref:`Behavior <mongorestore-behavior-access-usage>`
+- :ref:`Behavior <mongorestore-behavior-access-usage>`
+- :ref:`manual-tutorial-backup-and-restore`
+- :ref:`backup-sharded-dumps`