[GitHub] flimzy commented on a change in pull request #268: Rewrite sharding documentation

[GitBox <gi...@apache.org>]

flimzy commented on a change in pull request #268: Rewrite sharding documentation
URL: https://github.com/apache/couchdb-documentation/pull/268#discussion_r179913852
 
 

 ##########
 File path: src/cluster/sharding.rst
 ##########
 @@ -179,123 +328,114 @@ looks like this:
         }
     }
 
-After PUTting this document, it's like magic: the shards are now on node2 too!
-We now have ``n=2``!
+Now you can ``PUT`` this new metadata:
 
-If the shards are large, then you can copy them over manually and only have
-CouchDB sync the changes from the last minutes instead.
+.. code:: bash
 
-.. _cluster/sharding/move:
+    $ curl -X PUT $COUCH_URL:5986/_dbs/{name} -d '{...}'
 
-Moving Shards
-=============
+Replicating from old to new
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Add, then delete
-----------------
+Because shards are just CouchDB databases, you can replicate them
+around. In order to make sure the new shard receives any updates the old
+one processed while you were updating its metadata, you should replicate
+the old shard to the new one:
 
-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.
-#. Oh, no!: You have lost all writes made between 1 and 2.
+    $ curl -X POST $COUCH_URL:5986/_replicate -d '{ \
+        "source": $OLD_SHARD_URL,
+        "target": $NEW_SHARD_URL
+        }'
 
-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.
+This will bring the new shard up to date so that we can safely delete
+the old one.
 
-Moving
-------
+Delete old shard
+~~~~~~~~~~~~~~~~
+
+You can remove the old shard either by deleting its file or by deleting
+it through the private 5986 port:
 
 Review comment:
   Is there a preferred method we should encourage people to use?
   
   I'd vote for through the 5986 port, as it seems less error prone, but this whole process is already pretty manual, so maybe it doesn't really matter unless/until the whole thing can be done through the API.  Maybe others have thoughts? @wohali ?

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services