DOCS-136: revisions and editing to replication documentation based on kchodorow

Author: Sam Kleinman

source/administration/replica-sets.rst

@@ -36,16 +36,15 @@ Adding Members
 From to time, you may need to add an additional member to an existing
 :term:`replica set`. The data directory for the new member can:
 
-- have no data. In this case, you must copy all data as part of the
-  replication process before the member can exit ":term:`recovering`"
-  status, and become a :term:`secondary` member.
+- have no data. In this case, MongoDB must copy all data as part of
+  the replication process before the member can exit
+  ":term:`recovering`" status, and become a :term:`secondary`
+  member. This process can be time intensive, but does not require
+  administrator intervention.
 
-TODO: might be worth mentioning that "you" don't have to copy this data, it's done automatically.
-
-- copy the data directory from an existing member to limit the amount
-  of time that the recovery process takes.
-
-TODO: if you copy from an existing member, the new member will immediately be a secondary (not recovering).
+- copy the data directory from an existing member. The new member
+  becomes a secondary, and will catch up to the current state of the
+  replica set after a short interval.
 
   If the difference in the amount of time between the most recent
   operation and the most recent operation to the database exceeds the
@@ -54,22 +53,20 @@ TODO: if you copy from an existing member, the new member will immediately be a
   copy the data to the new system and begin replication within the
   window allowed by the :term:`oplog`.
 
-TODO: maybe mention you can do this with the db.printReplicationInfo() function.
+  Use :fun:`db.printReplicationInfo()` to check the current state of
+  replica set members with regards to the oplog.
 
 To add a member to an existing :term:`replica set`, deploy a new
 :program:`mongod` instance, specifying the name of the replica set
 (i.e. "setname" or ``replSet``) on the command line with the
 :option:`--replSet <mongod --replSet>` option or in the configuration
-with the :setting:`replSet`. Take note of the host name and
-port information for the new :program:`mongod` instance.
-
-TODO: "the configuration
-with" -> the configuration file with
+file with the :setting:`replSet`. Take note of the host name and port
+information for the new :program:`mongod` instance.
 
 Then, log in to the current primary using the :program:`mongo`
 shell. Issue the :func:`db.isMaster()` command when connected to *any*
 member of the set to determine the current :term:`primary`. Issue the
-following command to add the new member to the set.
+following command to add the new member to the set:
 
 .. code-block:: javascript
 
@@ -80,14 +77,15 @@ of the fields in a :data:`members` document, for example:
 
 .. code-block:: javascript
 
-   rs.add({host: "mongo2.example.net:27017", priority: 0, hidden: true})
-
-TODO: is the _id field automatically populated?
+   rs.add({_id: 1, host: "mongo2.example.net:27017", priority: 0, hidden: true})
 
 This configures a :term:`hidden member` that is accessible at
 ``mongo2.example.net:27018``. See ":data:`host <members[n].host>`,"
 ":data:`priority <members[n].priority>`," and ":data:`hidden
-<members[n].hidden>`" for more information about these settings.
+<members[n].hidden>`" for more information about these settings. When
+you specify a full configuration object with :fun:`rs.add()`, you must
+declare the ``_id`` field, which is not automatically populated in
+this case.
 
 .. seealso:: :doc:`/tutorial/expand-replica-set`
 
@@ -134,7 +132,14 @@ in the :program:`mongo` shell:
    rs.remove("mongo2.example.net:27018")
    rs.add({host: "mongo2.example.net:27019", priority: 0, hidden: true})
 
-TODO: prior to 2.2, this will almost never work because the _id will change.
+.. note::
+
+   Because the set member tracks its own replica set member ``_id``
+   which can cause conflicts when trying to re-add a previous member.
+
+   To resolve this issue, you can either restart the :program:`mongod`
+   process on the host that you're re-adding, or make sure that you
+   specify an "``_id``" in the :func:`rs.add()` document.
 
 Second, you may consider using the following procedure to use
 :func:`rs.reconfig()` to change the value of the
@@ -284,9 +289,9 @@ configurations and also describes the arbiter node type.
 Secondary-Only
 ~~~~~~~~~~~~~~
 
-Given a three node replica set, with member "``_id``" values of:
-``0``, ``1``, and ``2``, use the following sequence of operations in
-the :program:`mongo` shell to modify node priorities:
+Given a four-member replica set, with member "``_id``" values of:
+``0``, ``1``, ``2``, and ``3`` use the following sequence of
+operations in the :program:`mongo` shell to modify node priorities:
 
 .. code-block:: javascript
 
@@ -297,8 +302,6 @@ the :program:`mongo` shell to modify node priorities:
    cfg.members[3].priority = 2
    rs.reconfig(cfg)
 
-TODO: this is actually 4 nodes...
-
 This operation sets the member ``0`` to ``0`` and cannot become
 primary. Member ``3`` has a priority of ``2`` and will become primary,
 if eligible, under most circumstances. Member ``2`` has a priority of
@@ -335,15 +338,18 @@ operations in the :program:`mongo` shell:
    cfg.members[0].hidden = true
    rs.reconfig(cfg)
 
-TODO: it might be worth noting that, currently, you must send the reconfig command to
-a member that can become primary in the new configuration.  So, if members[0] is the
-current primary, this reconfig won't work.
-
 After re-configuring the set, the node with the "``_id``" of ``0``,
 has a priority of ``0`` so that it cannot become master, while the
 other nodes in the set will not advertise the hidden node in the
 :dbcommand:`isMaster` or :func:`db.isMaster()` output.
 
+.. note::
+
+   You must send the :func:`rs.reconfig()` command to a set member
+   that *can* become :term:`primary`. In the above example, if issue
+   the :func:`rs.reconfig()` operation to the member with the ``_id``
+   of ``0``, the operation will fail.
+
 .. seealso:: ":ref:`Replica Set Read Preference <replica-set-read-preference>`."
    ":data:`members[n].hidden`," ":data:`members[n].priority`,"
    and ":ref:`Replica Set Reconfiguration <replica-set-reconfiguration-usage>`."
@@ -535,9 +541,7 @@ were never replicated to the set so that the data set is in a
 consistent state. The :program:`mongod` program writes rolled back
 data to a :term:`BSON`.
 
-You can prevent Rollbacks prevented by ensuring safe writes by using
+You can prevent rollbacks prevented by ensuring safe writes by using
 the appropriate :term:`write concern`.
 
-TODO: "rollback" is not a proper noun.
-
 .. seealso:: ":ref:`Replica Set Elections <replica-set-elections>`"

source/administration/replication-architectures.rst

@@ -6,12 +6,10 @@ Replication Architectures
 
 There is no single :term:`replica set` architecture that is compatible
 or ideal for every deployment or environment. Indeed the flexibility
-of replica sets may be its greatest strenght. This document outlines
+of replica sets may be its greatest strength. This document outlines
 and describes the most prevalent deployment patterns for replica set
 administrators.
 
-TODO: strenght?
-
 .. seealso:: ":doc:`/administration/replica-sets`" and
    ":doc:`/reference/replica-configuration`."
 
@@ -65,9 +63,7 @@ architectural conditions are true:
   situation. If a member does not have this capability (i.e. resource
   constraints,) set its ``priority`` value to ``0``.
 
-- A majority *of the set's* members exist in the main data center.
-
-TODO: I don't understand why "of the set's" is emphasized.
+- A majority of the set's members exist in the main data center.
 
 .. seealso:: ":doc:`/tutorial/expand-replica-set`."
 
@@ -138,25 +134,19 @@ settings relevant for these kinds of nodes:
 - **Voting**: This changes the number of votes that a member of the
   set node has in elections for primary. In general use priority to
   control the outcome of elections, as weighting votes introduces
-  operational complexities and the potential. Only modify the number
-  of votes, if you need to have more than 7 members of a replica
-  set. (:ref:`see also <replica-set-non-voting-members>`.)
-
-TODO: and the potential... for royally screwing yourself.
+  operational complexities and risks set failure. Only modify the
+  number of votes, if you need to have more than 7 members of a
+  replica set. (:ref:`see also <replica-set-non-voting-members>`.)
 
 Backups
 ~~~~~~~
 
 For some deployments, keeping a replica set member for dedicated
-backup for dedicated backup purposes is operationally
-advantageous. Ensure this system is close, from a networking
-perspective, to the primary node or likely primary, and that the
-:term:`replication lag` is minimal or non-existent. You may wish to
-create a dedicated :ref:`hidden node <replica-set-hidden-members>` for
-the purpose of creating backups.
-
-TODO: Glitch in the matrix: "a replica set member for dedicated
-backup for dedicated backup purposes"
+backup purposes is operationally advantageous. Ensure this system is
+close, from a networking perspective, to the primary node or likely
+primary, and that the :term:`replication lag` is minimal or
+non-existent. You may wish to create a dedicated :ref:`hidden node
+<replica-set-hidden-members>` for the purpose of creating backups.
 
 If this node have journaling enabled, you can safely use standard
 :ref:`block level backup methods <block-level-backup>` to create a

source/applications/replication.rst

@@ -22,12 +22,11 @@ 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. :dbcommand:`getLastError` is configurable and can wait
-to return for journal writes or full disk flush. For replica sets,
-:dbcommand:`getLastError` can return only when the write
-operation has propagated to more than one node, or a majority of nodes
-in the cluster.
+:dbcommand:`getLastError` command. :dbcommand:`getLastError` is
+configurable and can wait to return for journal writes or full disk
+flush. For replica sets, :dbcommand:`getLastError` can return only
+when the write operation has propagated to more than one node, or a
+majority of nodes in the cluster.
 
 Many drivers have a "safe" or "write concern" mode that automatically
 issues a :dbcommand:`getLastError` command following write
@@ -65,12 +64,8 @@ replica set configuration. For instance:
 .. code-block:: javascript
 
    cfg = rs.conf()
-   cfg.settings.getLastErrorDefaults = "w: majority, fsync: false, j: true"
-   rs.reconfig(cfg)
-
-TODO: Incorrect getLastErrorDefaults setting:
    cfg.settings.getLastErrorDefaults = {w: "majority", fsync: false, j: true}
-
+   rs.reconfig(cfg)
 
 When the new configuration is active, the effect of the
 :dbcommand:`getLastError` operation will wait until the write

source/core/replication-internals.rst

@@ -27,18 +27,20 @@ will reflect writes within one second of the primary. However, various
 exceptional situations may cause secondaries lag behind further. See
 :term:`replication lag` for details.
 
-All nodes send heartbeats to all other nodes, and will import
-operations into its oplog from the node with the lowest "ping" time.
+All nodes send heartbeats to all other nodes, and can import
+operations to into its oplog from any other node in the
+cluster.
 
-TODO: the lowest "ping" time thing is very specific to 2.0, it wasn't true in 1.8 and probably will be different again in 2.2.  Not sure if you care or not.
+.. In 2.0, replicas would import entries from the member lowest
+.. "ping," This wasn't true in 1.8 and will likely change in 2.2.
 
 .. _replica-set-implementation:
 
 Implementation
 --------------
 
 MongoDB uses :term:`single master replication` to ensure that the
-database remains consistent. However, clients possible to modify the
+database remains consistent. However, clients may modify the
 :ref:`read preferences <replica-set-read-preference>` on a
 per-connection basis in order to distribute read operations to the
 secondary members of a replica set. Read-heavy deployments may achieve
@@ -50,8 +52,6 @@ section for more about ":ref:`read preference
 <replica-set-read-preference>`" and ":ref:`write concern
 <replica-set-write-concern>`."
 
-TODO: "However, clients possible..."
-
 .. note::
 
    Use :func:`db.getReplicationInfo()` from a secondary node
@@ -115,12 +115,10 @@ member should become primary.
 Elections are the process that the members of a replica set use to
 select the primary node in a cluster. Elections follow two events:
 primary node that "steps down" or a :term:`secondary` member that
-looses contact with a :term:`primary` node. All members have one vote
+loses contact with a :term:`primary` node. All members have one vote
 in an election, and every :program:`mongod` can veto an election. A
 single member's veto will invalidate the election.
 
-TODO: sp: looses
-
 An existing primary will step down in response to the
 :dbcommand:`replSetStepDown` command, or if it sees that one of
 the current secondaries is eligible for election *and* has a higher

source/core/replication.rst

@@ -16,9 +16,7 @@ the secondary nodes replicate from the primary asynchronously.
 Database replication with MongoDB, as with other systems, adds redundancy, helps to
 ensure high availability, simplifies certain administrative tasks
 such as backups, and may increase read capacity. Most production
-deployments are or should use replication.
-
-TODO: "are or should use replication."  are use replication?
+deployments are using or should use replication.
 
 If you're familiar with other database systems, you may think about
 replica sets as a more sophisticated form of traditional master-slave replication. [#master-slave]_
@@ -194,11 +192,11 @@ remain a secondary.
 
 .. note::
 
-   When an election occurs, the :program:`mongod` instances will close
-   all client connections. This ensures that the clients maintain an accurate
-   view of the :term:`replica set` and helps prevent :term:`rollbacks <rollback>`.
-
-TODO: it's actually just when a primary steps down that connections are closed.
+   When the current :term:`primary` steps down and triggers an
+   election, the :program:`mongod` instances will close all client
+   connections. This ensures that the clients maintain an accurate
+   view of the :term:`replica set` and helps prevent :term:`rollbacks
+   <rollback>`.
 
 .. seealso:: ":ref:`Replica Set Election Internals <replica-set-election-internals>`"
 
@@ -256,35 +254,24 @@ Rollbacks
 ~~~~~~~~~
 
 In some :term:`failover` situations :term:`primary` nodes will have
-accepted write operations that have replicated to the
+accepted write operations that have *not* replicated to the
 :term:`secondaries <secondary>` after a failover occurs. This case is
 rare and typically occurs as a result of a network partition with
 replication lag. When this node (the former primary) rejoins the
 :term:`replica set` and attempts to continue replication as a
-secondary those operations the former primary must revert these
-operations or "rolled back" these operations to maintain database
+secondary the former primary must revert these
+operations or "roll back" these operations to maintain database
 consistency across the replica set.
 
-TODO: ":term:`primary` nodes will have
-accepted write operations that have replicated to the
-:term:`secondaries <secondary>`" -> have not replicated to the secondary
-
-TODO: "as a
-secondary those operations the former primary must revert these
-operations or" those operations...these operations
-
 MongoDB writes the rollback data to a :term:`BSON` file in the
 database's :setting:`dbpath` directory. Use :doc:`bsondump
 </reference/bsondump>` to read the contents of these rollback files
 and then manually apply the changes to the new primary. There is no
 way for MongoDB to appropriately and fairly handle rollback situations
-without manual intervention. Since rollback situations require an
-administrator's direct intervention, users should strive to avoid
-rollbacks as much as possible. Until an administrator applies this
-rollback data, the former primary remains in a "rollback" status.
-
-TODO: "Until an administrator applies this
-rollback data, the former primary remains in a "rollback" status." Untrue!  ROLLBACK state should automatically correct itself and the server will end up in SECONDARY state.
+without manual intervention. Even after the node completes the
+rollback and returns to secondary status, administrators will need to
+apply or decide to ignore the rollback data. MongoDB users should strive to avoid
+rollbacks as much as possible.
 
 The best strategy for avoiding all rollbacks is to ensure :ref:`write
 propagation <replica-set-write-concern>` to all or some of the
@@ -297,15 +284,6 @@ that might create rollbacks.
    megabytes of data. If your system needs to rollback more than 300
    MB, you will need to manually intervene to recover this data.
 
-.. note::
-
-   After a rollback occurs, the former primary will remain in a
-   "rollback" mode until the administrator deals with the rolled back
-   data and restarts the :program:`mongod` instance. Only then can the
-   node becomes a normal :term:`secondary` terms.
-
-TODO: not true...
-
 Application Concerns
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -455,11 +433,12 @@ the existing members.
    :term:`Journaling <journal>`, provides single-instance
    write durability. The journaling greatly improves the reliability
    and durability of a database. Unless MongoDB runs with journaling, when a
-   MongoDB instance terminates ungracefully, the database can loose up to 60 seconds of data,
-   and the database may remain in an inconsistent state and
-   unrecoverable state.
+   MongoDB instance terminates ungracefully, the database can end in a
+   corrupt and unrecoverable state.
 
-TODO: this isn't true.  If you are running w/out journaling and mongod terminates "ungracefully" you can lose _all_ data.  Also, you should assume, after a crash w/out journaling, that the db is in an inconsistent (i.e., corrupt) state.
+   You should assume that a database, running without journaling, that
+   suffers a crash or unclean shutdown is in corrupt or inconsistent
+   state.
 
    **Use journaling**, however, do not forego proper replication
    because of journaling.