From 3f85f40227563063becc2b8c99ac17e1ddb5fc0a Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 1 Nov 2012 18:50:42 -0400 Subject: [PATCH 1/2] DOCS-703 & DOCS-249 Remove the term safe. Edits to rs write concern --- source/administration/replica-sets.txt | 37 +++--- source/applications/replication.txt | 118 ++++++++------------ source/core/replication.txt | 17 ++- source/faq/replica-sets.txt | 17 ++- source/faq/sharding.txt | 6 +- source/includes/fact-write-concerns.rst | 5 + source/includes/note-duplicate-id-feild.rst | 5 + source/reference/command/getLastError.txt | 3 + source/reference/command/moveChunk.txt | 4 +- source/reference/glossary.txt | 3 + source/reference/method/db.getLastError.txt | 9 +- source/reference/mongorestore.txt | 2 +- source/reference/replica-configuration.txt | 15 ++- source/release-notes/2.2.txt | 5 + 14 files changed, 121 insertions(+), 125 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index b65caee68fc..6e6e03f12fa 100644 --- a/source/administration/replica-sets.txt +++ b/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 ` 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 diff --git a/source/applications/replication.txt b/source/applications/replication.txt index d6781d10cbd..53b9d6e12ed 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -14,8 +14,8 @@ 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: @@ -23,94 +23,71 @@ This document describes those options and their implications. 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 ` :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 `. +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 -`. 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 +`. 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 - ` 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 diff --git a/source/core/replication.txt b/source/core/replication.txt index 32300a4a739..b1883e93ad7 100644 --- a/source/core/replication.txt +++ b/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 `. - - 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 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 ` diff --git a/source/faq/replica-sets.txt b/source/faq/replica-sets.txt index 424d346264f..8b4d8d232f3 100644 --- a/source/faq/replica-sets.txt +++ b/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? --------------------------------------- diff --git a/source/faq/sharding.txt b/source/faq/sharding.txt index 54fa1a15b0b..9781ca88031 100644 --- a/source/faq/sharding.txt +++ b/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 diff --git a/source/includes/fact-write-concerns.rst b/source/includes/fact-write-concerns.rst index c66ab176052..d07cf213f78 100644 --- a/source/includes/fact-write-concerns.rst +++ b/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 ` and :doc:`/applications/write-operations` for more information. diff --git a/source/includes/note-duplicate-id-feild.rst b/source/includes/note-duplicate-id-feild.rst index 4e098e6e848..9ead3c74446 100644 --- a/source/includes/note-duplicate-id-feild.rst +++ b/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 ` + to + :ref:`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 diff --git a/source/reference/command/getLastError.txt b/source/reference/command/getLastError.txt index 4c6b95cbafe..56154dd526b 100644 --- a/source/reference/command/getLastError.txt +++ b/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 `" and ":method:`db.getLastError()`." diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt index 46462268e4d..38c71c0dd36 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -32,8 +32,8 @@ moveChunk chunk to. :param _secondaryThrottle: Optional. Set to ``false`` by - default. Provides :ref:`write concern - ` support for chunk + default. Provides :term:`write concern` + support for chunk migrations. If you set ``_secondaryThrottle`` to ``true``, during chunk diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 419bc1d3e00..4224265506c 100644 --- a/source/reference/glossary.txt +++ b/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 `. priority diff --git a/source/reference/method/db.getLastError.txt b/source/reference/method/db.getLastError.txt index 64ebb66ffd9..788d2778322 100644 --- a/source/reference/method/db.getLastError.txt +++ b/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 `" and ":dbcommand:`getLastError`." diff --git a/source/reference/mongorestore.txt b/source/reference/mongorestore.txt index 4e568cb2f46..33bca89fcc4 100644 --- a/source/reference/mongorestore.txt +++ b/source/reference/mongorestore.txt @@ -183,7 +183,7 @@ Options .. versionadded:: 2.2 - Specifies the :ref:`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 diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index a99a0d2cc74..5ef7228784e 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -161,8 +161,8 @@ Configuration Variables **Default**: none Used to represent arbitrary values for describing or tagging members - for the purposes of extending :ref:`write concern - ` to allow configurable data center + for the purposes of extending :term:`write concern` + to allow configurable data center awareness. Use in conjunction with :data:`settings.getLastErrorModes` and @@ -392,9 +392,14 @@ use the following form: Tag Sets -------- -Tag sets provide custom and configurable :ref:`write concern -` and :ref:`read preferences -`. This section will outline the process +.. todo When draft/core/write-operations.txt goes live, change this below: + write-concern + to + write-operations-write-concern + +Tag sets provide custom and configurable :term:`write concern` +and :ref:`read preferences ` +for a :term:`replica set`. This section will outline the process for specifying tags for a replica set, for more information see the full documentation of the behavior of :ref:`tags sets write concern ` and :ref:`tag sets for read preference diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 8dd51e7e483..11b7d9d7a66 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -218,6 +218,11 @@ on specific shards. For example, with tag aware sharding, you can ensure that data is closest to the application servers that use that data most frequently. +.. todo When draft/core/write-operations.txt goes live, change this below: + write-concern + to + write-operations-write-concern + Shard tagging controls data location, and is complementary but separate from replica set tagging, which controls :ref:`read preference ` and :ref:`write concern From c5d23f05cf186e6ef4836454672338040e2d4059 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 1 Nov 2012 18:53:34 -0400 Subject: [PATCH 2/2] DOCS-703 & DOCS-249 minor edit --- source/reference/replica-configuration.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index 5ef7228784e..6a448e69de8 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -398,7 +398,7 @@ Tag Sets write-operations-write-concern Tag sets provide custom and configurable :term:`write concern` -and :ref:`read preferences ` +and :term:`read preferences ` for a :term:`replica set`. This section will outline the process for specifying tags for a replica set, for more information see the full documentation of the behavior of :ref:`tags sets write concern