Safe change 703

source/administration/replica-sets.txt

@@ -699,8 +699,9 @@ Possible causes of replication lag include:
 - **Concurrency**
 
   In some cases, long-running operations on the primary can block
-  replication on secondaries. You can use :term:`write concern` to
-  prevent write operations from returning if replication cannot keep up
+  replication on secondaries. To prevent this, configure :term:`write concern`
+  to require confirmation of replication to secondaries, as described in :ref:`replica-set-write-concern`.
+  This prevents write operations from returning if replication cannot keep up
   with the write load.
 
   Use the :term:`database profiler` to see if there are slow queries
@@ -709,27 +710,19 @@ Possible causes of replication lag include:
 - **Appropriate Write Concern**
 
   If you are performing a large data ingestion or bulk load operation
-  that requires a large number of writes to the primary, the
+  that requires a large number of writes to the primary, and if :term:`write concern` is disabled, the
   secondaries will not be able to read the oplog fast enough to keep
-  up with changes. Setting some level of write concern can
-  slow the overall progress of the batch but will prevent the
-  secondary from falling too far behind.
-
-  To prevent this, use write concern so that MongoDB will perform
-  a safe write (i.e. call :dbcommand:`getLastError`) after every 100,
-  1,000, or other designated number of operations.
-  This provides an opportunity for secondaries to catch up with the primary.
-  Using safe writes, even in batches, can impact write throughout;
-  however, calling :dbcommand:`getLastError` will prevents the
-  secondaries from falling too far behind the primary.
+  up with changes.
+
+  To prevent this, use :dbcommand:`getLastError` to enable write concern
+  so that MongoDB confirms success after every 100, 1,000, or other
+  designated number of operations. This provides an opportunity for
+  secondaries to catch up with the primary.
 
   For more information see:
 
-  - :ref:`replica-set-write-concern`.
-  - The :ref:`replica-set-oplog-sizing` topic in the :doc:`/core/replication` document.
-  - The :ref:`replica-set-oplog` topic in the :doc:`/core/replication-internals` document.
-  - The :ref:`replica-set-procedure-change-oplog-size` topic in this document.
-  - The :doc:`/tutorial/change-oplog-size` tutorial.
+  - :ref:`replica-set-write-concern`
+  - :ref:`replica-set-oplog-sizing`
 
 .. _replica-set-troubleshooting-check-connection:
 
@@ -870,7 +863,8 @@ operational errors:
 In many senses, :ref:`rollbacks <replica-set-rollbacks>` represent a
 graceful recovery from an impossible failover and recovery situation.
 
-Rollbacks occur when a primary accepts writes that other members of
+Rollbacks occur if :term:`write concern` is disabled and if
+a primary accepts writes that other members of
 the set do not successfully replicate before the primary steps
 down. When the former primary begins replicating again it performs a
 "rollback." Rollbacks remove those operations from the instance that
@@ -879,8 +873,7 @@ consistent state. The :program:`mongod` program writes rolled back
 data to a :term:`BSON` file that you can view using
 :program:`bsondump`, applied manually using :program:`mongorestore`.
 
-You can prevent rollbacks by ensuring safe writes by using
-the appropriate :term:`write concern`.
+You can prevent rollbacks by enabling :term:`write concern`.
 
 .. include:: /includes/seealso-elections.rst
 

source/applications/replication.txt

@@ -14,103 +14,80 @@ This document describes those options and their implications.
    shards are also replica sets provide the same configuration options
    with regards to write and read operations.
 
-.. the :ref:`write-concern` tag is here for the moment. At some point
-   we'll break this into its own document.
+.. todo When the draft/core/write-operations.txt doc goes live
+   remove the write-concern tag below.
 
 .. _write-concern:
 .. _replica-set-write-concern:
 
 Write Concern
 -------------
 
-When a :term:`client` sends a write operation to a database server, the
-operation returns without waiting for the operation to succeed or
-complete by default. To check if write operations have succeeded, use the
-:dbcommand:`getLastError` command. :dbcommand:`getLastError` supports the following options
-that allow you to tailor the level of "write concern" provided by the
-command's return or acknowledgment:
+.. todo When draft/core/write-operations.txt goes live, add this link:
+   :ref:`write-operations-write-concern`
 
-- no options.
+MongoDB's built-in :term:`write concern` confirms the success of write
+operations to a :term:`replica set's <replica set>` :term:`primary`.
+Write concern issues the :dbcommand:`getLastError` command after write
+operations to return an object with error information or confirmation
+that there are no errors.
 
-  Confirms that the :program:`mongod` instance received the write
-  operations. When your application receives this response, the
-  :program:`mongod` instance has committed the write operation to the
-  in-memory representation of the database. This provides a simple and
-  low-latency level of write concern and will allow your application
-  to detect situations where the :program:`mongod` instance becomes
-  inaccessible or insertion errors caused by :ref:`duplicate key
-  errors <index-type-unique>`.
+The MongoDB Fall 2012 driver release enables write concern by default.
 
-- ``j`` or "journal" option.
+When enabled by default, write concern confirms write operations only on the primary.
+You can configure write concern to confirm write operations to
+additional replica set members as well by issuing the
+:dbcommand:`getLastError` command with the ``w`` option.
 
-  Confirms the above, and that the :program:`mongod` instance has
-  written the data to the on-disk journal. This ensures that the data
-  is durable if :program:`mongod` or the server itself crashes or
-  shuts down unexpectedly.
+The ``w`` option confirms that write operations have replicated to the
+specified number of replica set members, including the primary. You can
+either specify a number or specify ``majority``, which ensures the write
+propagates to a majority of set members. The following example ensures
+the operation has replicated to two members (the primary and one other
+member):
 
-- ``fsync`` option.
-
-  .. deprecated:: 1.8
-
-  Do not use the ``fsync`` option. Confirms that the :program:`mongod`
-  has flushed the in-memory representation of the data to the
-  disk. Instead, use the ``j`` option to ensure durability.
-
-- ``w`` option. Only use with replica sets.
-
-  Confirms that the write operation has replicated to the specified
-  number of replica set members. You may specify a specific number of
-  servers *or* specify ``majority`` to ensure that the write
-  propagates to a majority of set members. The default value of ``w``
-  is ``1``.
+.. code-block:: javascript
 
-You may combine multiple options, such as ``j`` and ``w``, into a
-single :dbcommand:`getLastError` operation.
+   db.runCommand( { getLastError: 1, w: 2 } )
 
-Many drivers have a "safe" mode or "write concern" that automatically
-issues :dbcommand:`getLastError` after write operations to ensure
-the operations complete. Safe mode provides confirmation of
-write operations, but safe writes can take longer
-to return and are not required in all applications. Consider the
-following operations:
+The following example ensures the write operation has replicated to a
+majority of the members of the set.
 
 .. code-block:: javascript
 
    db.runCommand( { getLastError: 1, w: "majority" } )
-   db.getLastErrorObj("majority")
 
-These equivalent :dbcommand:`getLastError` operations ensure that write
-operations return only after a write operation has replicated to a
-majority of the members of the set.
+When write concern is enabled by default, the default value of ``w`` is
+``1``, which confirms write operations only to the primary.
 
-.. note::
+If you specify a ``w`` value greater than the number of members that
+hold a copy of the data (i.e., greater than the number of
+non-:term:`arbiter` members), the operation blocks until those members
+become available. This can cause the operation to block forever. To
+specify a timeout threshold for the :dbcommand:`getLastError` operation,
+use the ``wtimeout`` argument. The following example sets the timeout to
+5000 milliseconds:
+
+.. code-block:: javascript
 
-   If you specify a ``w`` value greater than the number of available
-   non-:term:`arbiter` replica set members, the operation will block
-   until those members become available. This could cause the
-   operation to block forever. To specify a timeout threshold for the
-   :dbcommand:`getLastError` operation, use the ``wtimeout`` argument.
+   db.runCommand( { getlasterror: 1, w: 2, wtimeout:5000 } )
 
-You can also configure your own "default" :dbcommand:`getLastError` behavior
-for the replica set. Use the :data:`settings.getLastErrorDefaults`
-setting in the :doc:`replica set configuration
-</reference/replica-configuration>`. For instance:
+You can configure your own "default" :dbcommand:`getLastError` behavior
+for a replica set. Use the :data:`settings.getLastErrorDefaults` setting
+in the :doc:`replica set configuration
+</reference/replica-configuration>`. The following sequence of commands
+creates a configuration that waits for the write operation to complete
+on a majority of the set members before returning:
 
 .. code-block:: javascript
 
    cfg = rs.conf()
    cfg.settings = {}
-   cfg.settings.getLastErrorDefaults = {w: "majority", j: true}
+   cfg.settings.getLastErrorDefaults = {w: "majority"}
    rs.reconfig(cfg)
 
-When the new configuration is active, the :dbcommand:`getLastError`
-operation waits for the write operation to complete on a majority
-of the set members before returning. Specifying ``j: true`` makes
-:dbcommand:`getLastError` wait for a complete commit of the
-operations to the journal before returning.
-
-The :data:`getLastErrorDefaults` setting only affects :dbcommand:`getLastError`
-commands with *no* other arguments.
+The :data:`getLastErrorDefaults` setting affects only those
+:dbcommand:`getLastError` commands that have *no* other arguments.
 
 .. note::
 
@@ -172,8 +149,8 @@ configuration, see the appropriate :ref:`driver` API documentation.
    Read preferences affect how an application selects which member
    to use for read operations. As a result read
    preferences dictate if the application receives stale or
-   current data from MongoDB. Use appropriate :ref:`write concern
-   <replica-set-write-concern>` policies to ensure proper data
+   current data from MongoDB. Use appropriate :term:`write concern`
+   policies to ensure proper data
    replication and constancy.
 
    If read operations account for a large percentage of your
@@ -390,7 +367,6 @@ However, the following tag sets would *not* be able to fulfill this query:
    { "disk": "ssd", "use": "production", "rack": 3 }
    { "disk": "spinning", "use": "reporting", "mem": "32" }
 
-
 Therefore, tag sets make it possible to ensure that read operations
 target specific members in a particular data center or
 :program:`mongod` instances designated for a particular class of

source/core/replication.txt

@@ -244,15 +244,14 @@ minimal or no difference between applications using
 There are two major concepts that *are* important to consider when
 working with replica sets:
 
-1. :ref:`Write Concern <replica-set-write-concern>`.
-
-   By default, MongoDB clients receive no response from the server to
-   confirm successful write operations. Most drivers provide a
-   configurable "safe mode," where the server will return a response
-   for all write operations using :dbcommand:`getLastError`. For
-   replica sets, :term:`write concern` is configurable to ensure that
-   secondary members of the set have replicated operations before the
-   write returns.
+1. :term:`Write Concern <write concern>`.
+
+   Write concern sends a MongoDB client a response from the server to
+   confirm successful write operations. In MongoDB's Fall 2012 driver
+   release, write concern is enabled by default. For replica sets,
+   :term:`write concern` is configurable to ensure that secondary
+   members of the set have replicated operations before the write
+   returns.
 
 2. :ref:`Read Preference <replica-set-read-preference>`
 

source/faq/replica-sets.txt

@@ -135,19 +135,16 @@ instances can safely restart without any administrator intervention.
    Journaling is enabled by default on all 64-bit
    builds of MongoDB v2.0 and greater.
 
-Are write operations durable without ``getLastError``?
-------------------------------------------------------
+Are write operations durable without write concern enabled?
+-----------------------------------------------------------
 
 Yes.
 
-However, if you want confirmation that a given write has arrived
-safely at the server, you must also run the :dbcommand:`getLastError`
-command after each write. If you enable your driver's :term:`write
-concern`, or "safe mode", the driver will automatically send
-:dbcommand:`getLastError` this command. If you want to guarantee that
-a given write syncs to the journal, you must pass the ``{j: true}``
-option :dbcommand:`getLastError` (or specify it as part of the write
-concern).
+However, if you want confirmation that a given write has arrived at the
+server, use :term:`write concern`. The :dbcommand:`getLastError` command
+enables write concern. In the Fall 2012 driver release version of
+MongoDB write concern is enabled by default. See the
+:doc:`/applications/drivers` documentation for your driver.
 
 How many arbiters do replica sets need?
 ---------------------------------------

source/faq/sharding.txt

@@ -222,8 +222,10 @@ run the following command:
 What does ``writebacklisten`` in the log mean?
 ----------------------------------------------
 
-The writeback listener is a process that opens a long poll to detect
-non-safe writes sent to a server and to send them back to the correct
+The writeback listener is a process that opens a long poll to relay
+writes back from a :program:`mongod` or :program:`mongos` after migrations
+to make sure they have not gone to the wrong server.
+The writeback listener sends writes back to the correct
 server if necessary.
 
 These messages are a key part of the sharding infrastructure and should

source/includes/fact-write-concerns.rst

@@ -5,5 +5,10 @@ command to confirm the result of the write operation:
 
    { getLastError: 1 }
 
+.. todo When draft/core/write-operations.txt goes live, change this below:
+   write-concern
+   to
+   write-operations-write-concern
+
 Refer to the documentation on :ref:`write concern <write-concern>` and
 :doc:`/applications/write-operations` for more information.

source/includes/note-duplicate-id-feild.rst

@@ -1,5 +1,10 @@
 .. note::
 
+.. todo When draft/core/write-operations.txt goes live, change:
+   :ref:`write concern <write-concern>`
+   to
+   :ref:`write concern <write-operations-write-concern>`
+
    The ``_id`` field must hold a unique value. If you specify a value
    for ``_id`` that already exists in a collection the
    :program:`mongod` will produce a duplicate key exception and reject

source/reference/command/getLastError.txt

@@ -51,5 +51,8 @@ getLastError
                             timeframe, the :dbcommand:`getLastError`
                             command will return with an error status.
 
+   .. todo When draft/core/write-operations.txt goes live, add this below:
+      :ref:`write-operations-write-concern`
+
    .. seealso:: ":ref:`Replica Set Write Concern <replica-set-write-concern>`"
       and ":method:`db.getLastError()`."

source/reference/command/moveChunk.txt

@@ -32,8 +32,8 @@ moveChunk
               chunk to.
 
    :param _secondaryThrottle: Optional. Set to ``false`` by
-                              default. Provides :ref:`write concern
-                              <write-concern>` support for chunk
+                              default. Provides :term:`write concern`
+                              support for chunk
                               migrations.
 
    If you set ``_secondaryThrottle`` to ``true``, during chunk

source/reference/glossary.txt

@@ -590,6 +590,9 @@ Glossary
       set>`, you can configure write concern to confirm replication to a
       specified number of members.
 
+      .. todo When draft/core/write-operations.txt goes live, add this below:
+         :ref:`write-operations-write-concern`
+
       .. seealso:: :ref:`Write Concern for Replica Sets <replica-set-write-concern>`.
 
    priority

source/reference/method/db.getLastError.txt

@@ -8,9 +8,12 @@ db.getLastError()
 
    :returns: The last error message string.
 
-   In many situation MongoDB drivers and users will follow a write
-   operation with this command in order to ensure that the write
-   succeeded. Use "safe mode" for most write operations.
+   Sets the level of :term:`write concern` for confirming the success of write operations.
+
+   .. QUESTION Should we list the parameters here?
+
+   .. todo When draft/core/write-operations.txt goes live, add this to the seealso below:
+      :ref:`write-operations-write-concern`
 
    .. seealso:: ":ref:`Replica Set Write Concern <replica-set-write-concern>`"
       and ":dbcommand:`getLastError`."

source/reference/mongorestore.txt

@@ -183,7 +183,7 @@ Options
 
    .. versionadded:: 2.2
 
-   Specifies the :ref:`write concern <write-concern>` for each write
+   Specifies the :term:`write concern` for each write
    operation that :program:`mongorestore` writes to the target
    database. By default, :program:`mongorestore` waits for the write
    operation to return on 1 member of the set (i.e. the