From 0b6874fb2320ce01004a49a549fe7556099a5f72 Mon Sep 17 00:00:00 2001 From: Kristina Date: Fri, 24 Feb 2012 17:10:13 -0500 Subject: [PATCH] comments on replication docs --- source/administration/replica-sets.rst | 21 +++++++++++++++++++ .../replication-architectures.rst | 9 ++++++++ source/applications/replication.rst | 4 ++++ source/core/replication-internals.rst | 6 ++++++ source/core/replication.rst | 19 +++++++++++++++++ source/reference/replica-configuration.rst | 5 +++++ source/reference/replica-status.rst | 12 +++++++++++ source/reference/replication-info.rst | 3 +++ 8 files changed, 79 insertions(+) diff --git a/source/administration/replica-sets.rst b/source/administration/replica-sets.rst index 5f960f81b85..ec6eaf31e45 100644 --- a/source/administration/replica-sets.rst +++ b/source/administration/replica-sets.rst @@ -40,9 +40,13 @@ From to time, you may need to add an additional member to an existing replication process before the member can exit ":term:`recovering`" status, and become a :term:`secondary` member. +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). + If the difference in the amount of time between the most recent operation and the most recent operation to the database exceeds the length of the :term:`oplog` on the existing members, then the new @@ -50,6 +54,8 @@ From to time, you may need to add an additional member to an existing 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. + 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 @@ -57,6 +63,9 @@ To add a member to an existing :term:`replica set`, deploy a new 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 + 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 @@ -73,6 +82,8 @@ of the fields in a :data:`members` document, for example: rs.add({host: "mongo2.example.net:27017", priority: 0, hidden: true}) +TODO: is the _id field automatically populated? + This configures a :term:`hidden member` that is accessible at ``mongo2.example.net:27018``. See ":data:`host `," ":data:`priority `," and ":data:`hidden @@ -123,6 +134,8 @@ 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. + Second, you may consider using the following procedure to use :func:`rs.reconfig()` to change the value of the :data:`members[n].host` field to reflect the new hostname or port @@ -284,6 +297,8 @@ 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 @@ -320,6 +335,10 @@ 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 @@ -519,4 +538,6 @@ data to a :term:`BSON`. 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 `" diff --git a/source/administration/replication-architectures.rst b/source/administration/replication-architectures.rst index 796f9a10b7b..8740be8c237 100644 --- a/source/administration/replication-architectures.rst +++ b/source/administration/replication-architectures.rst @@ -10,6 +10,8 @@ of replica sets may be its greatest strenght. 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,6 +67,8 @@ architectural conditions are true: - 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. + .. seealso:: ":doc:`/tutorial/expand-replica-set`." .. _replica-set-geographical-distribution: @@ -138,6 +142,8 @@ settings relevant for these kinds of nodes: of votes, if you need to have more than 7 members of a replica set. (:ref:`see also `.) +TODO: and the potential... for royally screwing yourself. + Backups ~~~~~~~ @@ -149,6 +155,9 @@ perspective, to the primary node or likely primary, and that the create a dedicated :ref:`hidden node ` for the purpose of creating backups. +TODO: Glitch in the matrix: "a replica set member for dedicated +backup for dedicated backup purposes" + If this node have journaling enabled, you can safely use standard :ref:`block level backup methods ` to create a backup of this node. Otherwise, if your underlying system does not diff --git a/source/applications/replication.rst b/source/applications/replication.rst index c0f310a9068..5a1e7682d7a 100644 --- a/source/applications/replication.rst +++ b/source/applications/replication.rst @@ -68,6 +68,10 @@ replica set configuration. For instance: 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} + + 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 nodes before writing. By diff --git a/source/core/replication-internals.rst b/source/core/replication-internals.rst index 7db55018f3b..978d35d8c38 100644 --- a/source/core/replication-internals.rst +++ b/source/core/replication-internals.rst @@ -30,6 +30,8 @@ exceptional situations may cause secondaries lag behind further. See All nodes send heartbeats to all other nodes, and will import operations into its oplog from the node with the lowest "ping" time. +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. + .. _replica-set-implementation: Implementation @@ -48,6 +50,8 @@ section for more about ":ref:`read preference `" and ":ref:`write concern `." +TODO: "However, clients possible..." + .. note:: Use :func:`db.getReplicationInfo()` from a secondary node @@ -115,6 +119,8 @@ looses 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 diff --git a/source/core/replication.rst b/source/core/replication.rst index c21495f2eb9..fe27cafbf12 100644 --- a/source/core/replication.rst +++ b/source/core/replication.rst @@ -18,6 +18,8 @@ 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? + 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]_ In master-slave replication, a ":term:`master`" node accepts writes while one or more @@ -196,6 +198,8 @@ remain a secondary. all client connections. This ensures that the clients maintain an accurate view of the :term:`replica set` and helps prevent :term:`rollbacks `. +TODO: it's actually just when a primary steps down that connections are closed. + .. seealso:: ":ref:`Replica Set Election Internals `" .. _replica-set-node-priority: @@ -261,6 +265,14 @@ secondary those operations the former primary must revert these operations or "rolled 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 `" -> 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 ` to read the contents of these rollback files @@ -271,6 +283,9 @@ 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. + The best strategy for avoiding all rollbacks is to ensure :ref:`write propagation ` to all or some of the nodes in the set. Using these kinds of policies prevents situations @@ -289,6 +304,8 @@ that might create rollbacks. data and restarts the :program:`mongod` instance. Only then can the node becomes a normal :term:`secondary` terms. +TODO: not true... + Application Concerns ~~~~~~~~~~~~~~~~~~~~ @@ -442,6 +459,8 @@ the existing members. and the database may remain in an inconsistent state 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. + **Use journaling**, however, do not forego proper replication because of journaling. diff --git a/source/reference/replica-configuration.rst b/source/reference/replica-configuration.rst index 772b0bbc87d..01cd067d092 100644 --- a/source/reference/replica-configuration.rst +++ b/source/reference/replica-configuration.rst @@ -57,6 +57,8 @@ Configuration Variables :data:`members[n].host` cannot hold a value that resolves to ``localhost`` or the local interface. +TODO: unless all of the members in the set do. You can have all-or-none localhost. + .. data:: members[n].arbiterOnly *Optional*. @@ -81,6 +83,9 @@ Configuration Variables become a master, or if any clients ever issue queries against this instance. +TODO: whether, not weather +Probably "Do not set to false if a member *can* become a master..." + Omitting index creation, and thus this setting, may be useful, **if**: diff --git a/source/reference/replica-status.rst b/source/reference/replica-status.rst index ea1a83601ab..c20a5a6d243 100644 --- a/source/reference/replica-status.rst +++ b/source/reference/replica-status.rst @@ -18,6 +18,8 @@ in heartbeats sent to the current instance by other members of the replica set: because of the frequency of heartbeats, these data can be at most 2 seconds out of date. +TODO: not sure I'd commit to 2 seconds, as the timeout before heartbeat fails is ~20 seconds. So maybe "this data can be a few seconds out-of-date"? + .. note:: The :program:`mongod` that you issue the :dbcommand:`replSetGetStatus` @@ -38,6 +40,8 @@ Statuses The ``set`` value is the name of the replica set, configured in the :setting:`replSet` setting. +TODO: might want to mention it's the same as the _id in rs.conf(), but no one's ever expressed confusion about that, so minor point. + .. status:: rs.status.date The value of the ``date`` field is an :term:`ISODate` of the @@ -53,6 +57,8 @@ Statuses the state of the member. These integers map to states, as described in the following table: +TODO: an integer between 0 and 10, now. + ========== ========================================================== **Number** **State** ---------- ---------------------------------------------------------- @@ -76,6 +82,8 @@ Statuses `" for an overview of the values included in these documents. +TODO: this is missing the syncedTo field, only present on secondaries (and recovering nodes) that shows who they're syncing from. + .. _repl-set-member-statuses: Member Statuses @@ -121,12 +129,16 @@ Member Statuses A 64-bit timestamp of the last operation applied to this member of the replica set from the :term:`oplog`. +TODO: 32-bit (t+i=64-bit) + .. status:: members.optime.i An incremented field, which reflects the number of operations in since the last time stamp. This value only increases if there are more than one operation per second. +TODO: ...if there is more + .. status:: members[n].optimeDate An :term:`ISODate` formatted date string that reflects the last diff --git a/source/reference/replication-info.rst b/source/reference/replication-info.rst index 54c03df1d48..dfe3da021d7 100644 --- a/source/reference/replication-info.rst +++ b/source/reference/replication-info.rst @@ -73,6 +73,9 @@ The following fields appear in the output of Returns a time stamp for the first (i.e. earliest) operation in the :term:`oplog`. Compare this value to :status:`now`. +TODO: copypasta with tFirst +Also, please don't encourage people to compare this with "now", they should compare it to the last time they did a write. tLast could be days ago, but if there haven't been any writes since, lag is 0. + .. status:: now Returns a time stamp reflecting the current time. The shell process