From 37f12ffc530dfb69ecad5aa94b89678c2070b0e4 Mon Sep 17 00:00:00 2001 From: Scott Hernandez Date: Mon, 6 Aug 2012 23:54:12 -0700 Subject: [PATCH 1/3] cleanup, success is not what getLastError returns, for foilures and reporting what occurred like after an update --- source/applications/replication.txt | 40 ++++++++++++++--------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index e3ef74c937a..57be850cb14 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -21,20 +21,18 @@ 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 +or complete. To verify that the operation has completed, +and to check for an error, 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 +:dbcommand:`getLastError` to wait until the journal flushes to disk or 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 +Many drivers have a "safe" mode or "write concern" 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. +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. Using the ``w: "majority"`` option for @@ -47,17 +45,18 @@ of the replica set members: .. 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. .. note:: - :dbcommand:`getLastError` assumes the current host, + :dbcommand:`getLastError` assumes the primary replica node, 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``. + member of the replica set acknowledges the write operation. The current + primary always counts as ``w: 1``. Using ``w: 0`` makes no sense and should + not be done. You can also configure a "default" :dbcommand:`getLastError` behavior on the replica set configuration. For instance: @@ -65,19 +64,18 @@ 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. +operation has completed on a majority of the set members before writing. By +specifying ``j: true`` a complete commit of the operations to the +journal is all that :dbcommand:`getLastError` requires to return. 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 From e9811e35e40809af290880af6407b660e5ed0ba6 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Tue, 7 Aug 2012 12:21:43 -0400 Subject: [PATCH 2/3] DOCS-379 write concern revision --- source/applications/replication.txt | 89 +++++++++++++++++------------ 1 file changed, 53 insertions(+), 36 deletions(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 57be850cb14..cc2fc19fd39 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -21,45 +21,61 @@ 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 complete. To verify that the operation has completed, -and to check for an error, use the -:dbcommand:`getLastError` command. You can configure -:dbcommand:`getLastError` to wait until the journal flushes to disk or 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. +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: -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. +- without options. Confirms that the server has received the write + operations, and modified the :program:`mongod` instances in-memory + representation of the data. -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: +- with the ``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. + +- 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.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 primary replica node, - therefore, ``w: 2`` waits until the :term:`primary` and one other - member of the replica set acknowledges the write operation. The current - primary always counts as ``w: 1``. Using ``w: 0`` makes no sense and should - not be done. + :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. -You can also configure a "default" :dbcommand:`getLastError` behavior on the -replica set configuration. For instance: + Using ``w: 0`` is valid but does not produce useful behavior. + +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 @@ -67,14 +83,15 @@ replica set configuration. For instance: 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 completed on a majority of the set members before writing. By -specifying ``j: true`` a complete commit of the operations to the -journal is all that :dbcommand:`getLastError` requires to return. 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` +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 @@ -516,7 +533,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` From fe9bd7bea188746219296ce2c3c6ba7647475436 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Thu, 9 Aug 2012 23:15:05 -0400 Subject: [PATCH 3/3] DOCS-379 revision of write concern page. --- source/applications/replication.txt | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index cc2fc19fd39..e1138b67fe4 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -30,13 +30,15 @@ levels are: operations, and modified the :program:`mongod` instances in-memory representation of the data. -- with the ``journal`` option. Confirms that the server has committed +- 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. + 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 @@ -70,7 +72,12 @@ returns. set, or the :term:`primary` and one other member of the replica set before confirming the write operation. - Using ``w: 0`` is valid but does not produce useful behavior. + 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. + + ``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