From 841b75bbd08112f634a4aaef1efd3e0ca5de311c Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Tue, 9 Apr 2013 17:46:31 -0400 Subject: [PATCH 1/2] DOCS-1360 add write concern tags info to getLastError --- source/core/write-concern.txt | 15 ++++++---- source/reference/command/getLastError.txt | 32 ++++++++++++++-------- source/reference/replica-configuration.txt | 16 +++++++---- 3 files changed, 41 insertions(+), 22 deletions(-) diff --git a/source/core/write-concern.txt b/source/core/write-concern.txt index 1381da2c805..fceb1a9fd3e 100644 --- a/source/core/write-concern.txt +++ b/source/core/write-concern.txt @@ -98,6 +98,8 @@ have *no* other arguments. .. seealso:: :ref:`write-operations-write-concern` and :ref:`connections-write-concern` +.. _custom-write-concerns: + Custom Write Concerns ~~~~~~~~~~~~~~~~~~~~~ @@ -140,7 +142,7 @@ in the :program:`mongo` shell: .. code-block:: javascript cfg = rs.conf() - cfg.settings = { getLastErrorModes: { use2: { "use": 2 } } } + cfg.settings = { getLastErrorModes: { multiUse: { "use": 2 } } } rs.reconfig(cfg) .. these examples need to be better so that they avoid overwriting @@ -152,7 +154,7 @@ To use this mode pass the string ``multiUse`` to the ``w`` option of .. code-block:: javascript - db.runCommand( { getLastError: 1, w: use2 } ) + db.runCommand( { getLastError: 1, w: "multiUse" } ) Specific Custom Write Concerns ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -197,14 +199,15 @@ To use this mode pass the string ``san`` to the ``w`` option of .. code-block:: javascript - db.runCommand( { getLastError: 1, w: san } ) + db.runCommand( { getLastError: 1, w: "san" } ) This operation will not return until a replica set member with the tag ``disk.san`` returns. -You may set a custom write concern mode as the default write concern -mode using :data:`~local.system.replset.settings.getLastErrorDefaults` -replica set as in the following setting: +To use a custom ``getLastErrorMode`` as the default write concern +of a replica set, specify the error mode in the +:data:`~local.system.replset.settings.getLastErrorDefaults` +of a replica set as follows: .. code-block:: javascript diff --git a/source/reference/command/getLastError.txt b/source/reference/command/getLastError.txt index c276b43b4e5..19223702aa1 100644 --- a/source/reference/command/getLastError.txt +++ b/source/reference/command/getLastError.txt @@ -26,17 +26,27 @@ getLastError flush. If :program:`mongod` does not have journaling enabled, this option has no effect. - :param w: When running with replication, this is the number of - servers to replicate to before returning. A ``w`` value of - 1 indicates the primary only. A ``w`` value of 2 - includes the primary and at least one secondary, etc. - In place of a number, you may also set ``w`` to - ``majority`` to indicate that the command should wait - until the latest write propagates to a majority of - replica set members. If using ``w``, you should also use - ``wtimeout``. Specifying a value for ``w`` without also - providing a ``wtimeout`` may cause - :dbcommand:`getLastError` to block indefinitely. + :param integer w: + The number of replica set members to replicate a write operation to + before returning. A value of ``1`` indicates to wait until the + primary member acknowledges the write operation before returning. + A ``w`` value of 2 includes the primary and at least one secondary, etc. + If using ``w``, you should also use + ``wtimeout``. Specifying a value for ``w`` without also + providing a ``wtimeout`` may cause + :dbcommand:`getLastError` to block indefinitely + + :param w: + In place of a number, you may also set ``w`` to + ``"majority"`` to indicate that the command should wait + until the latest write propagates to a majority of + replica set members. + + :param w: + Alternately, ``w`` may be a string corresponding to a custom + :data:`getLastErrorMode `. + See :ref:`tag-sets-custom-write-concern` and :ref:`custom-write-concerns` + for information on defining and using custom tag sets and write concerns. :param boolean fsync: If ``true``, wait for :program:`mongod` to write this data to disk before returning. Defaults to diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index d5ebc8b77b3..ecc1537cb28 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -427,9 +427,10 @@ Tag sets provide custom and configurable :term:`write concern` and :term:`read preferences ` for a :term:`replica set`. This section outlines the process for specifying tags for a replica set, for more information see the -full documentation of the behavior of ref:`tags sets for write concern -` and :ref:`tag sets for read preference -`. +full documentation of the behavior of +:ref:`tag sets for write concern ` +and +:ref:`tag sets for read preference `. .. important:: @@ -518,6 +519,7 @@ resemble the following: ] } +.. _tag-sets-custom-write-concern: Configure Tag Sets for Custom Multi-Data Center Write Concern Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -599,7 +601,7 @@ replica set as follows in the :program:`mongo` shell: rs.reconfig(conf) Now, the following write concern operation will only return after the -write operation propagates to at least two different racks in the +write operation propagates to at least two different racks in each facility: .. code-block:: javascript @@ -636,7 +638,7 @@ disk type of ``ssd``, you could use the following tag set: { disk: "ssd" } However, to create comparable write concern modes, you would specify a -different set of +different set of tags in the :data:`~local.system.replset.settings.getLastErrorModes` configuration. Consider the following sequence of operations in the :program:`mongo` shell: @@ -684,6 +686,10 @@ Additionally, you can specify the ``ssd`` write concern mode, as in the following operation, to ensure that a write operation propagates to at least one instance with an SSD. +.. code-block:: javascript + + db.runCommand( { getLastError: 1, w: "ssd" } ) + .. [#read-and-write-tags] Since read preferences and write concerns use the value of fields in tag sets differently, larger deployments will have some redundancy. From 0c782c0a97ae7fb52113353b669158652de7958e Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Wed, 24 Apr 2013 10:12:16 -0400 Subject: [PATCH 2/2] DOCS-1360 address @tychoish comments --- source/core/write-concern.txt | 5 +++-- source/reference/command/getLastError.txt | 9 +++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/source/core/write-concern.txt b/source/core/write-concern.txt index fceb1a9fd3e..69953570339 100644 --- a/source/core/write-concern.txt +++ b/source/core/write-concern.txt @@ -204,8 +204,9 @@ To use this mode pass the string ``san`` to the ``w`` option of This operation will not return until a replica set member with the tag ``disk.san`` returns. -To use a custom ``getLastErrorMode`` as the default write concern -of a replica set, specify the error mode in the +To use a custom +:data:`getLastErrorMode ` +as the default write concern of a replica set, specify the error mode in the :data:`~local.system.replset.settings.getLastErrorDefaults` of a replica set as follows: diff --git a/source/reference/command/getLastError.txt b/source/reference/command/getLastError.txt index 19223702aa1..71dca4a11d5 100644 --- a/source/reference/command/getLastError.txt +++ b/source/reference/command/getLastError.txt @@ -27,14 +27,15 @@ getLastError journaling enabled, this option has no effect. :param integer w: - The number of replica set members to replicate a write operation to - before returning. A value of ``1`` indicates to wait until the - primary member acknowledges the write operation before returning. + The number of replica set members that must acknowledge receipt of a + write operation before returning. + A value of ``1`` indicates to wait until the primary member acknowledges + the write operation before returning. A ``w`` value of 2 includes the primary and at least one secondary, etc. If using ``w``, you should also use ``wtimeout``. Specifying a value for ``w`` without also providing a ``wtimeout`` may cause - :dbcommand:`getLastError` to block indefinitely + :dbcommand:`getLastError` to block indefinitely. :param w: In place of a number, you may also set ``w`` to