Write concern revisions for DOCS-379

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 </reference/replica-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 <database command>` read and
 return data from the database, all of the official drivers support
-full :ref:`read preference mode semantics <replica-set-read-preference-modes>` 
+full :ref:`read preference mode semantics <replica-set-read-preference-modes>`
 for the following commands:
 
 - :dbcommand:`group`