diff --git a/source/includes/note-repair.rst b/source/includes/note-repair.rst new file mode 100644 index 00000000000..15dab13bfc3 --- /dev/null +++ b/source/includes/note-repair.rst @@ -0,0 +1,6 @@ +.. note:: + + When using :term:`journaling `, there is almost never + any need to run :dbcommand:`repairDatabase`. In the event of an + unclean shutdown, the server will be able restore the data files + to a pristine state automatically. diff --git a/source/includes/warning-repair.rst b/source/includes/warning-repair.rst new file mode 100644 index 00000000000..c961ea807ec --- /dev/null +++ b/source/includes/warning-repair.rst @@ -0,0 +1,8 @@ +.. warning:: + + In general, if you have an intact copy of your data, such as + would exist on a very recent backup or an intact member of a + :term:`replica set`, **do not** use :dbcommand:`repairDatabase` + or related options like :func:`db.repairDatabase()` in the + :program:`mongo` shell or :option:`mongod --repair`. Restore + from an intact copy of your data. diff --git a/source/reference/commands.txt b/source/reference/commands.txt index c0784ba5f14..ff024feb877 100644 --- a/source/reference/commands.txt +++ b/source/reference/commands.txt @@ -1454,18 +1454,24 @@ Administration .. dbcommand:: repairDatabase + .. include:: /includes/warning-repair.rst + + .. include:: /includes/note-repair.rst + 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. If your :program:`mongod` instance is not running with journaling - and you experience an unexpected system restart or crash, you + 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. As a side effect, the :dbcommand:`repairDatabase` command will - compact the database, providing functionality equivalent to the - :dbcommand:`compact` command. Use the following syntax. + compact the database, as the :dbcommand:`compact` command and + reduce the total size of the data files on disk. Use the following + syntax: .. code-block:: javascript @@ -1485,6 +1491,9 @@ Administration - Use the shell to run the above command, as above. + - Use the :func:`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 issue this command as a user that has access to MongoDB's data @@ -1499,23 +1508,11 @@ Administration .. note:: This command will fail if your database is not a master or - primary. If you need to repair a secondary or slave node, - first restart the node as a standalone mongod by omitting the - :option:`--replSet ` or :option:`--slave - ` options, as necessary. - - - You may use the following shell helper: - - .. code-block:: javascript - - db.repairDatabase(); - - .. note:: - - When using :term:`journaling `, there is almost never any need to - run :dbcommand:`repairDatabase`. In the event of an unclean - shutdown, the server will be able restore the data files to a - pristine state automatically. + 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 ` + or :option:`--slave ` options, as necessary. .. dbcommand:: shutdown diff --git a/source/reference/javascript.txt b/source/reference/javascript.txt index f9eea90cb0a..2770c06d8ad 100644 --- a/source/reference/javascript.txt +++ b/source/reference/javascript.txt @@ -1014,26 +1014,18 @@ Database Removes the specified username from the database. -.. function:: db.repairDatabase() - Checks and repairs errors and inconsistencies with the data - storage. This function is analogous to a ``fsck`` operation for - file systems. Additionally, the function compacts the database to - minimize the current database's storage utilization, similar to the - :dbcommand:`compact` command. +.. function:: db.repairDatabase() - This function has the same effect as using the run-time option - ":option:`mongod --repair`," but only operates on the current - database. + .. include:: /includes/warning-repair.rst - This command provides a wrapper around the database command - ":dbcommand:`repairDatabase`". - - .. warning:: + .. include:: /includes/note-repair.rst - In general, if you have an intact :term:`replica set` member, - do not use :func:`db.repairDatabase()` and restore from the - other replica member. + :func:`db.repairDatabase()` provides a wrapper around the database + command :dbcommand:`repairDatabase`, and has the same effect as + the run-time option :option:`mongod --repair` option, limited to + *only* the current database. See :dbcommand:`repairDatabase` for + full documentation. .. function:: db.runCommand(command) diff --git a/source/reference/mongod.txt b/source/reference/mongod.txt index 77c428232df..60073b9bb4c 100644 --- a/source/reference/mongod.txt +++ b/source/reference/mongod.txt @@ -334,15 +334,13 @@ Options .. option:: --repair - Runs a repair routine on all databases. + Runs a repair routine on all databases. This is equivalent + to shutting down and running :dbcommand:`repairDatabase` database + command on all databases. - .. note:: + .. include:: /includes/warning-repair.rst - Because :program:`mongod` rewrites all of the database files - during the repair routine, if you do not run :option:`--repair` - under the same user account as :program:`mongod` usually runs, - you will need to run ``chown`` on your database files to correct - the permissions before starting :program:`mongod` again. + .. include:: /includes/note-repair.rst .. versionchanged:: 2.1.2 @@ -357,6 +355,7 @@ Options :program:`mongod` cleanly and restart with the :option:`--repair` option. + .. option:: --repairpath Specifies the root directory containing MongoDB data files, to use