Skip to content

Commit

Permalink
Clean up wording in "Add, then delete" section (#192)
Browse files Browse the repository at this point in the history
* Clean up wording in "Add, then delete" section
  • Loading branch information
dannyroberts authored and wohali committed Nov 1, 2017
1 parent 999ca00 commit 279d117
Showing 1 changed file with 17 additions and 11 deletions.
28 changes: 17 additions & 11 deletions src/cluster/sharding.rst
Original file line number Diff line number Diff line change
Expand Up @@ -198,19 +198,25 @@ Moving Shards
Add, then delete
----------------

In the world of CouchDB there is no such thing as moving. You can add a new
replica to a shard and then remove the old replica, thereby creating the
illusion of moving. If you try to uphold this illusion with a database that have
``n=1``, you might find yourself in the following scenario:

#. Copy the shard to a new node.
In the world of CouchDB there is no such thing as "moving" shards, only adding
and removing shard replicas.
You can add a new replica of a shard and then remove the old replica,
thereby creating the illusion of moving.
If you do this for a database that has ``n=1``,
you might be caught by the following mistake:

#. Copy the shard onto a new node.
#. Update the metadata to use the new node.
#. Delete the shard on the old node.
#. Lose all writes made between 1 and 2.

As the reality "I added a new replica of the shard X on node Y and then I waited
for them to sync, before I removed the replica of shard X from node Z." is a bit
tedious, people and this documentation tend to use the illusion of moving.
#. Oh, no!: You have lost all writes made between 1 and 2.

To avoid this mistake, you always want to make sure
that both shards have been live for some time
and that the shard on your new node is fully caught up
before removing a shard on an old node.
Since "moving" is a more conceptually (if not technically)
accurate description of what you want to do,
we'll use that word in this documentation as well.

Moving
------
Expand Down

0 comments on commit 279d117

Please sign in to comment.