DOCSP-33862-mongorestore-example (#146)

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

* DOCSP-33862-mongorestore-example

---------

Co-authored-by: jason-price-mongodb <[email protected]>

Author: jason-price-mongodb

source/mongodump.txt

@@ -626,20 +626,26 @@ Options
 
 .. option:: --oplog
 
-   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`.
+   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.
 
+   To apply oplog entries from the ``oplog.bson`` file in the restore
+   operation, use :option:`mongorestore --oplogReplay`. You can use
+   ``mongodump --oplog`` together with ``mongorestore --oplogReplay`` to
+   ensure the data is current and has all the writes that occurred
+   during the dump.
+
    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 back up individual replica sets while still accepting writes, use
+   ``--oplog``. To back up sharded clusters with ``mongodump``, see
+   :ref:`backup-sharded-dumps`.
+
    .. important::
 
       A ``mongodump`` running with ``--oplog`` fails if
@@ -650,11 +656,9 @@ 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`` has no effect when running ``mongodump`` on a ``mongos``
+   instance to dump the entire contents of a sharded cluster.
+
    ``--oplog`` only works against nodes that maintain an
    :term:`oplog`. This includes all members of a replica set.
 
@@ -731,6 +735,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

@@ -553,12 +553,14 @@ Options
 .. option:: --oplogReplay
 
    After restoring the database dump, replays the :term:`oplog` entries
-   from a 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. 
+   from an ``oplog.bson`` file.
 
+   To apply oplog entries from the ``oplog.bson`` file in the restore,
+   use ``mongorestore --oplogReplay``. You can use :option:`mongodump
+   --oplog` together with ``mongorestore --oplogReplay`` to ensure the
+   data is current and has all the writes that occurred during the dump
+   operation.
+
    ``mongorestore`` searches for any valid source  for the bson file
    in the following locations:
 
@@ -625,7 +627,13 @@ 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::
+
+      Use ``oplogLimit`` with caution: manually specifying the oplog
+      entries to apply might cause corruption and inconsistencies in the
+      restored data.
+
    You must use :option:`--oplogLimit` in conjunction with the
    :option:`--oplogReplay` option.
 
@@ -639,7 +647,12 @@ Options
    file at the top level of the dump directory, ``mongorestore`` returns an 
    error.
 
+   .. warning::
 
+      Use ``oplogFile`` with caution: manually specifying the oplog
+      entries to apply might cause corruption and inconsistencies in the
+      restored data.
+   
 .. option:: --convertLegacyIndexes
 
    .. versionadded:: 100.0.0
@@ -859,6 +872,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.
 
@@ -331,14 +331,32 @@ 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 
+----------------------------------------------------
+
+``mongodump`` 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.
+
+To apply the oplog entries in the restore, use :option:`mongorestore
+--oplogReplay`. You can use :option:`mongodump --oplog` together with
+``mongorestore --oplogReplay`` to ensure the data is current and has all
+the writes that occurred during the dump operation. However, if any
+writes occur after ``mongodump`` completes, those writes aren't captured
+in that dump operation.
+
+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
@@ -387,7 +405,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::
 
@@ -430,4 +448,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`