diff --git a/source/applications/replication.txt b/source/applications/replication.txt index e3ef74c937a..e1138b67fe4 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -21,63 +21,85 @@ Write Concern When a :term:`client` sends a write operation to a database server, the operation will return without waiting for the operation to succeed -or return. To verify that the operation is successful, use the -:dbcommand:`getLastError` command. You can configure -:dbcommand:`getLastError` to return after journal flushes to disk or -after the data itself flushes to disk. For replica sets, you can -configure :dbcommand:`getLastError` to return only after the write -operation has propagated to more than one member of the set or to a -majority of the set's members. - -Many drivers have a "safe" or "write concern" mode that automatically -issues a :dbcommand:`getLastError` command following write -operations to ensure that they succeed. "Safe mode," -provides confirmation of write operations to clients, which is often -the expected method of operation, and is particularly useful when -using standalone instances. - -However, safe writes can take longer to return and are not required in -all applications. Using the ``w: "majority"`` option for -:dbcommand:`getLastError`, write operations to a replica set will -return only after a write operation has replicated to a majority of -the members of the set. At the :program:`mongo` shell, use the -following command to ensure that writes have propagated to a majority -of the replica set members: +or complete. The :dbcommand:`getLastError` command provides a way to +check if write operations have succeeded, and provides operations to +require various levels of write concern. [#write-concern]_ These +levels are: + +- without options. Confirms that the server has received the write + operations, and modified the :program:`mongod` instances in-memory + representation of the data. + +- with the ``j`` or "journal" option. Confirms that the server has committed + the data to the on-disk journal. This ensures that the data will be + durable in the event that :program:`mongod` experiences an + unexpected shut down. + +- with the ``fsync`` option. Confirms that the :program:`mongod` has + flushed the write operation to disk. Do not use this operation in + normal production situations: use ``j`` to ensure this level of + durability. + +- for replica sets, with the ``w`` option. Confirms that the write + operation has replicated to the specified number of + replica set members. You may specify a number of servers *or* + ``majority`` to ensure that the write propagates to a majority of + set members. + +Many drivers have a "safe" mode or "write concern" that automatically +issues a :dbcommand:`getLastError` command following write operations +to ensure that they complete. "Safe mode," provides confirmation of +write operations to the client. However, safe writes can take longer +to return and are not required in all applications. Consider the +following operations. .. code-block:: javascript db.runCommand( { getLastError: 1, w: "majority" } ) - db.getLastError("majority") + db.getLastErrorObj("majority") -You may also specify ``w: 2`` so that the write operation replicates -to a second member before the command returns. +Following a write operation, these equivalent +:dbcommand:`getLastError` operations will ensure that write operations +return only after a write operation has replicated to a majority of +the members of the set. You might also specify ``w: 2`` so that the +write operation replicates to a second member before the command +returns. .. note:: - :dbcommand:`getLastError` assumes the current host, - therefore, ``w: 2`` waits until the :term:`primary` and one other - member of the replica set commits the write operation. The current - primary always counts as ``w: 1``. + :dbcommand:`getLastError` assumes the primary replica node, which + is equivalent to ``w: 1``. ``w: 2`` waits until 2 members of the + set, or the :term:`primary` and one other member of the replica set + before confirming the write operation. + + If you specify a ``w`` value greater than the number running + members of the set, the operation will block until those numbers + join the set. Use the ``wtimeoute`` argument to specify a timeout + threshold for the :dbcommand:`getLastError` operation. -You can also configure a "default" :dbcommand:`getLastError` behavior on the -replica set configuration. For instance: + ``w: 0`` is valid but has no effect, and is equivelent to a no-op. + +You can also configure a "default" :dbcommand:`getLastError` behavior +for the replica set configuration. Use the +:data:`settings.getLastErrorDefaults` setting in the :doc:`replica set +configuration `. For instance: .. code-block:: javascript cfg = rs.conf() - cfg.settings.getLastErrorDefaults = {w: "majority", fsync: false, j: true} + cfg.settings.getLastErrorDefaults = {w: "majority", j: true} rs.reconfig(cfg) -When the new configuration is active, the effect of the -:dbcommand:`getLastError` operation will wait until the write -operation has succeeded on a majority of the set members before writing. By -specifying ``fsync: false`` and ``j: true`` a successful commit of -the operation to the journal is all that :dbcommand:`getLastError` -requires to return succesullly, rather than a full flush to disk. Use this the -:data:`getLastErrorDefaults`" setting on the sever level to define the -standards for a set-wide "safe mode." The default setting will only -affect :dbcommand:`getLastError` commands with *no* other -arguments. +When the new configuration is active, the :dbcommand:`getLastError` +operation will wait for the write operation to complete on a majority +of the set members before returning. By specifying ``j: true``, +:dbcommand:`getLastError` waits for a complete commit of the +operations to the journal before returning. + +Use the :data:`getLastErrorDefaults`" setting in the :ref:`replica +set` configuration to define the standards for a set-wide "safe mode." +The default setting will only affect :dbcommand:`getLastError` +commands with *no* other arguments. .. index:: read preference .. index:: slaveOk @@ -518,7 +540,7 @@ Database Commands Because some :term:`database commands ` read and return data from the database, all of the official drivers support -full :ref:`read preference mode semantics ` +full :ref:`read preference mode semantics ` for the following commands: - :dbcommand:`group`