DOCS-1313: Document repairDatabase options

source/reference/command/repairDatabase-field.yaml

@@ -0,0 +1,32 @@
+object:
+  name: repairDatabase
+  type: dbcommand
+field:
+  optional: false
+  type: field
+name: preserveClonedFilesOnFailure
+type: boolean
+position: 1
+description: |
+  When ``true``, ``repairDatabase`` will not delete temporary files
+  in the backup directory on error, and all new files are created
+  with the "backup" instead of "_tmp" directory prefix. By default
+  ``repairDatabase`` does not delete temporary files, and uses the
+  "_tmp" naming prefix for new files.
+---
+object:
+  name: repairDatabase
+  type: dbcommand
+field:
+  optional: false
+  type: field
+name: backupOriginalFiles
+type: boolean
+position: 2
+description: |
+  When ``true``, ``repairDatabase`` moves old database files to the
+  backup directory instead of deleting them before moving new files
+  into place. New files are created with the "backup" instead of "_tmp"
+  directory prefix. By default, ``repairDatabase`` leaves temporary
+  files unchanged, and uses the "_tmp" naming prefix for new files.
+...

source/reference/command/repairDatabase.txt

@@ -4,69 +4,122 @@ repairDatabase
 
 .. default-domain:: mongodb
 
+.. contents::
+   :backlinks: none
+   :local:
+
+Definition
+----------
+
 .. dbcommand:: repairDatabase
 
-   .. include:: /includes/warning-repair.rst
+   Checks and repairs errors and inconsistencies in data storage.
+   :dbcommand:`repairDatabase` is analogous to a ``fsck`` command for
+   file systems. Run the :dbcommand:`repairDatabase` command to ensure
+   data integrity after the system experiences an unexpected system
+   restart or crash, if:
+
+   #. The :program:`mongod` instance is not running with
+      :term:`journaling <journal>` enabled.
+
+      .. include:: /includes/note-repair.rst
 
-   .. include:: /includes/note-repair.rst
+   #. There are *no* other intact :term:`replica set` members with a complete
+      data set.
 
-   The :dbcommand:`repairDatabase` command checks and repairs errors and
-   inconsistencies with the data storage. The command is analogous to
-   a ``fsck`` command for file systems.
+      .. include:: /includes/warning-repair.rst
 
-   If your :program:`mongod` instance is not running with journaling
-   the system experiences an unexpected system restart or crash, and
-   you have *no* other intact replica set members with this data, you
-   should run the :dbcommand:`repairDatabase` command to ensure that
-   there are no errors in the data storage.
+   :dbcommand:`repairDatabase` has the following fields:
 
-   As a side effect, the :dbcommand:`repairDatabase` command will
-   compact the database, as the :dbcommand:`compact` command, and also
-   reduces the total size of the data files on disk. The
-   :dbcommand:`repairDatabase` command will also recreate all indexes
-   in the database. 
-
-   Use the following syntax:
+   .. include:: /reference/command/repairDatabase-field.rst
+
+   :dbcommand:`repairDatabase` takes the following form:
 
    .. code-block:: javascript
 
-        { repairDatabase: 1 }
-
-   Be aware that this command can take a long time to run if your
-   database is large. In addition, it requires a quantity of free disk
-   space equal to the size of your database. If you lack sufficient
-   free space on the same volume, you can mount a separate volume and
-   use that for the repair. In this case, you must run the command
-   line and use the :option:`--repairpath <mongod --repairpath>`
-   switch to specify the folder in which to store the temporary repair
-   files.
-
+      { repairDatabase: 1 }
+
+   You can explicitly set the options as follows:
+
+   .. code-block:: javascript
+
+      { repairDatabase: 1,
+        preserveClonedFilesOnFailure: <boolean>,
+        backupOriginalFiles: <boolean> }
+
    .. include:: /includes/warning-blocking-global.rst
 
-   This command is accessible via a number of different avenues. You
-   may:
+   .. note:: :dbcommand:`repairDatabase` requires free disk space equal to the size
+      of your current data set plus 2 gigabytes. If the volume that holds dbpath
+      lacks sufficent space, you can mount a separate volume
+      and use that for the repair. When mounting a separate volume for
+      :dbcommand:`repairDatabase` you must run :dbcommand:`repairDatabase`
+      from the command line and use the :option:`--repairpath <mongod --repairpath>`
+      switch to specify the folder in which to store
+      temporary repair files.
+
+   See :option:`mongod --repair` and :option:`mongodump --repair` for
+   information on these options.
+
+Behavior
+--------
+
+The :dbcommand:`repairDatabase` command compacts all collections in the
+database. It is identical to running the :dbcommand:`compact` command on
+each collection individually.
+
+:dbcommand:`repairDatabase` reduces the total size of the data files on
+disk. It also recreates all indexes in the database.
+
+The time requirement for :dbcommand:`repairDatabase` depends on the size of the
+data set.
+
+You may invoke :dbcommand:`repairDatabase` from multiple contexts:
+
+- Use the :program:`mongo` shell to run the command, as above.
+
+- Use the :method:`db.repairDatabase()` in the :program:`mongo`
+  shell.
+
+- Run :program:`mongod` directly from your system's shell. Make sure
+  that :program:`mongod` isn't already running, and that you invoke
+  :program:`mongod` as a user that has access to MongoDB's data files. Run
+  as:
+
+  .. code-block:: javascript
+
+     mongod --repair
+
+  To add a repair path:
+
+  .. code-block:: javascript
+
+     mongod --repair --repairpath /opt/vol2/data
+
+  .. note::
 
-   - Use the shell to run the above command, as above.
+     :program:`mongod --repair <mongod>` will fail if your database
+     is not a master or primary. In most cases, you should recover a
+     corrupt secondary using the data from an existing intact node. To
+     run repair on a secondary/slave restart the instance in standalone
+     mode without the :option:`--replSet <mongod --replSet>` or
+     :option:`--slave <mongod --slave>` options.
 
-   - Use the :method:`db.repairDatabase()` in the :program:`mongo`
-     shell.
+Example
+-------
 
-   - Run :program:`mongod` directly from your system's shell. Make sure
-     that :program:`mongod` isn't already running, and that you issue
-     this command as a user that has access to MongoDB's data
-     files. Run as: ::
+.. code-block:: javascript
 
-           $ mongod --repair
+   { repairDatabase: 1 }
 
-     To add a repair path: ::
+Using ``repairDatabase`` to Reclaim Disk Space
+----------------------------------------------
 
-           $ mongod --repair --repairpath /opt/vol2/data
+You should not use :dbcommand:`repairDatabase` for data recovery
+unless you have no other option.
 
-     .. note::
+However, if you trust that there is no corruption, and you have enough
+free space to perform a :dbcommand:`repairDatabase` command, then
+:dbcommand:`repairDatabase` is the appropriate (and the only) way to
+reclaim disk space.
 
-        This command will fail if your database is not a master or
-        primary. In most cases, you should recover a corrupt secondary
-        using the data from an existing intact node. If you must
-        repair a secondary or slave node, first restart the node as a
-        standalone mongod by omitting the :option:`--replSet <mongod --replSet>`
-        or :option:`--slave <mongod --slave>` options, as necessary.

source/reference/program/mongodump.txt

@@ -204,6 +204,9 @@ Options
    be in an inconsistent state as a result of an improper shutdown or
    :program:`mongod` crash.
 
+   .. note:: The --repair option uses aggressive data-recovery algorithms
+      that may produce a large amount of duplication.
+
 .. option:: --forceTableScan
 
    Forces :program:`mongodump` to scan the data store directly: