Skip to content

Commit 69d3567

Browse files
author
Bob Grabar
committed
DOCS-386 disambiguate initial sync and replication
1 parent 2580f26 commit 69d3567

14 files changed

+66
-58
lines changed

source/administration/journaling.txt

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,23 @@ Journaling
44

55
.. default-domain:: mongodb
66

7-
MongoDB uses *write ahead logging* or :term:`journaling <journal>` to
7+
MongoDB uses *write ahead logging* to an on-disk :term:`journal` to
88
guarantee :doc:`write operation </core/write-operations>` durability
9-
by way of a an on disk journal. Before applying a change to the data
10-
files, MongoDB writes this operation to the journal. Then, if MongoDB
11-
terminates or encounters an error unexpectedly before it can write the
9+
and to provide crash resiliency. Before applying a change to the data
10+
files, MongoDB writes the change operation to the journal. If MongoDB
11+
should terminate or encounter an error before it can write the
1212
data to disk, MongoDB can re-apply the write operation and maintain a
1313
consistent state.
1414

15-
Journaling ensures that :program:`mongodb` is crash resilient. *Without*
16-
a journal, if :program:`mongodb` exits unexpectedly, you must assume
17-
your data is in an inconsistent state and must either run
15+
*Without* a journal, if :program:`mongod` exits unexpectedly, you must assume
16+
your data is in an inconsistent state, and you must run either
1817
:doc:`repair </tutorial/recover-data-following-unexpected-shutdown>`
19-
or preferably :ref:`resync <replica-set-resync-stale-member>` from a
18+
or, preferably, :ref:`resync <replica-set-resync-stale-member>` from a
2019
clean member of the replica set.
2120

22-
When journaling is enabled, if :program:`mongodb` stops unexpectedly,
21+
With journaling enabled, if :program:`mongod` stops unexpectedly,
2322
the program can recover everything written to the journal, and the
24-
data is in a consistent state. By default, the greatest extent of lost
23+
data remains in a consistent state. By default, the greatest extent of lost
2524
writes, i.e., those not made to the journal, is no more than the last
2625
100 milliseconds.
2726

source/administration/monitoring.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -483,8 +483,8 @@ however, as replication lag grows, two significant problems emerge:
483483
integrity of your data set.
484484

485485
- Second, if the replication lag exceeds the length of the operation
486-
log (:term:`oplog`) then the secondary will have to resync all data
487-
from the :term:`primary` and rebuild all indexes. In normal
486+
log (:term:`oplog`) then MongoDB will have to perform an initial sync on the secondary, copying all data
487+
from the :term:`primary` and rebuilding all indexes. In normal
488488
circumstances this is uncommon given the typical size of the oplog,
489489
but it's an issue to be aware of.
490490

source/administration/replica-sets.txt

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -370,7 +370,7 @@ the following to prepare the new member's :term:`data directory <dbpath>`:
370370
difference in the amount of time between the most recent operation and
371371
the most recent operation to the database exceeds the length of the
372372
:term:`oplog` on the existing members, then the new instance will have
373-
to completely resynchronize, as described in
373+
to perform an initial sync, which completely resynchronizes the data, as described in
374374
:ref:`replica-set-resync-stale-member`.
375375

376376
Use :method:`db.printReplicationInfo()` to check the current state of
@@ -575,13 +575,13 @@ Resyncing a Member of a Replica Set
575575
When a secondary's replication process falls behind so far that
576576
:term:`primary` overwrites oplog entries that the secondary has not
577577
yet replicated, that secondary cannot catch up and becomes "stale."
578-
When that occurs, you must resync the member by removing its data and
579-
replacing it with up-to-date data.
578+
When that occurs, you must completely resynchronize the member by removing its data and
579+
performing an initial sync.
580580

581581
To do so, use one of the following approaches:
582582

583583
- Restart the :program:`mongod` with an empty data directory and let
584-
MongoDB's normal replication syncing feature restore the data. This
584+
MongoDB's normal initial syncing feature restore the data. This
585585
is the more simple option, but may take longer to replace the data.
586586

587587
See :ref:`replica-set-auto-resync-stale-member`.
@@ -598,9 +598,9 @@ To do so, use one of the following approaches:
598598
Automatically Resync a Stale Member
599599
```````````````````````````````````
600600

601-
This procedure relies on MongoDB's regular process for syncing a new
601+
This procedure relies on MongoDB's regular process for initially syncing a new
602602
member to restore the data on the stale member. For an overview of how
603-
MongoDB syncs :term:`replica sets <replica set>`, see the
603+
MongoDB initially syncs :term:`replica sets <replica set>`, see the
604604
:ref:`replica-set-syncing` section.
605605

606606
To resync the stale member:
@@ -624,7 +624,7 @@ To resync the stale member:
624624

625625
mongod --dbpath /data/db/ --replSet rsProduction
626626

627-
At this point, the :program:`mongod` will resync. This process may
627+
At this point, the :program:`mongod` will perform an initial sync. This process may
628628
take a long time, depending on the size of the database and speed
629629
of the network. Remember that this operation may have an impact on
630630
the working set and/or traffic to existing primary other members of

source/core/replication-internals.txt

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -255,14 +255,20 @@ and a majority of servers in one data center and one server in another.
255255
Syncing
256256
-------
257257

258-
In order to remain up-to-date with the current state of the :term:`replica set`,
259-
set members :term:`sync`, or copy, :term:`oplog` entries from other members.
258+
In order to remain up-to-date with the current state of the
259+
:term:`replica set`, set members :term:`sync`, or copy, :term:`oplog`
260+
entries from other members. Members sync data at two different points:
260261

261-
When a new member joins a set or an existing member restarts, the
262-
member waits to receive heartbeats from other members. By
263-
default, the member syncs from the *the closest* member of the
264-
set that is either the primary or another secondary with more recent
265-
oplog entries. This prevents two secondaries from syncing from each other.
262+
- "Initial sync" occurs when MongoDB creates new databases on a new or
263+
restored member, populating the the member with the replica set's
264+
data. When a new or restored member joins or rejoins a set, the member
265+
waits to receive heartbeats from other members. By default, the member
266+
syncs from the *the closest* member of the set that is either the
267+
primary or another secondary with more recent oplog entries. This
268+
prevents two secondaries from syncing from each other.
269+
270+
- "Replication" occurs continually after initial sync and keeps the
271+
member updated with changes to the replica set's data.
266272

267273
In version 2.0, secondaries only change sync targets if the connection
268274
between secondaries drops or produces an error.
@@ -282,5 +288,3 @@ For example:
282288
alternate facility, and if you add another secondary to the alternate
283289
facility, the new secondary will likely sync from the existing
284290
secondary because it is closer than the primary.
285-
286-
.. seealso:: :ref:`replica-set-resync-stale-member`

source/core/replication.txt

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -245,9 +245,8 @@ that might create rollbacks.
245245
[replica set sync] replSet syncThread: 13410 replSet too much data to roll back
246246

247247
In these situations you will need to manually intervene to either
248-
save data manually, or resync from a "current" member of the set by
249-
deleting the content of the existing:setting:`dbpath` directory to
250-
resume normal operation.
248+
save data manually or to perform an initial sync from a "current" member of the set by
249+
deleting the content of the existing :setting:`dbpath` directory.
251250

252251
For more information on failover, see:
253252

@@ -344,8 +343,8 @@ the first time, you can only change the size of the oplog by using the
344343

345344
In most cases, the default oplog size is sufficient. For example, if an
346345
oplog that is 5% of free disk space fills up in 24 hours of operations, then
347-
secondaries can stop copying entries from the oplog for 24 hours before
348-
they require full resyncing. However, most replica sets have much
346+
secondaries can stop copying entries from the oplog for up to 24 hours
347+
without becoming stale. However, most replica sets have much
349348
lower operation volumes, and their oplogs can hold a much larger
350349
number of operations.
351350

source/reference/command/replSetSyncFrom.txt

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,18 @@ replSetSyncFrom
88

99
.. versionadded:: 2.2
1010

11-
:option host: Specifies the name and port number of the set member
12-
that you want *this* member to sync from. Use
13-
the ``[hostname]:[port]`` form.
11+
:option host: Specifies the name and port number of the replica set member
12+
that this member replicates from. Use
13+
the ``[hostname]:[port]`` from.
1414

1515
:dbcommand:`replSetSyncFrom` allows you to explicitly configure
1616
which host the current :program:`mongod` will poll :term:`oplog`
1717
entries from. This operation may be useful for testing different
18-
patterns and in situations where a set member is not syncing from
19-
the host you want. The member to sync from must be a valid
20-
source for data in the set; a member of a replica set cannot sync from:
18+
patterns and in situations where a set member is not replicating from
19+
the host you want. The member to replicate from must be a valid
20+
source for data in the set.
21+
22+
A member cannot replicate from:
2123

2224
- itself.
2325
- an arbiter, because arbiters do not hold data.
@@ -26,9 +28,9 @@ replSetSyncFrom
2628
- a :program:`mongod` instance that is not a member of the same
2729
replica set.
2830

29-
If you attempt to sync from a member that is more than 10 seconds
31+
If you attempt to replicate from a member that is more than 10 seconds
3032
behind the current member, :program:`mongod` will return and log a
31-
warning, but *will* sync from such members.
33+
warning, but it *still will* replicate from such members.
3234

3335
The command has the following prototype form:
3436

@@ -52,6 +54,8 @@ replSetSyncFrom
5254

5355
.. note::
5456

57+
.. TODO this next para has a sentence that is missing a noun or verb or some such
58+
5559
:dbcommand:`replSetSyncFrom` provides a temporary override of
5660
default behavior. When you restart the :program:`mongod`
5761
instance, if the connection that the :program:`mongod` uses to

source/reference/configuration-options.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -643,9 +643,9 @@ Replication Options
643643
*Default:* false
644644

645645
In the context of :term:`replica set` replication, set this option
646-
to ``true`` if you have seeded this replica with a snapshot of the
646+
to ``true`` if you have seeded this member with a snapshot of the
647647
:term:`dbpath` of another member of the set. Otherwise the
648-
:program:`mongod` will attempt to perform a full sync.
648+
:program:`mongod` will attempt to perform an initial sync, as though the member were a new member.
649649

650650
.. warning::
651651

source/reference/local-database.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Collections on Replica Set Members
5050

5151
.. data:: local.replset.minvalid
5252

53-
This contains an object used internally by replica sets to track sync
53+
This contains an object used internally by replica sets to track replication
5454
status.
5555

5656
.. data:: local.slaves

source/reference/method/rs.syncFrom.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,6 @@ rs.syncFrom()
1111
Provides a wrapper around the :dbcommand:`replSetSyncFrom`, which
1212
allows administrators to configure the member of a replica set that
1313
the current member will pull data from. Specify the name of the
14-
member you want to sync from in the form of ``[hostname]:[port]``.
14+
member you want to replicate from in the form of ``[hostname]:[port]``.
1515

1616
See :dbcommand:`replSetSyncFrom` for more details.

source/reference/mongod.txt

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -487,9 +487,10 @@ Replication Options
487487
.. option:: --fastsync
488488

489489
In the context of :term:`replica set` replication, set this option
490-
if you have seeded this replica with a snapshot of the
490+
if you have seeded this member with a snapshot of the
491491
:term:`dbpath` of another member of the set. Otherwise the
492-
:program:`mongod` will attempt to perform a full sync.
492+
:program:`mongod` will attempt to perform an initial sync,
493+
as though the member were a new member.
493494

494495
.. warning::
495496

0 commit comments

Comments
 (0)