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

 ##########
 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:
   I'm ambivalent, with a slight preference for file deletion. The key is to 
update the cluster metadata first so that the shard is no longer "live" as far 
as the cluster is concerned; after that, the file is just detritus.
   
   As I mentioned in my review, port 5986 will go away with 3.0, so this 
section will need at least a partial rewrite sometime before then anyway.

----------------------------------------------------------------
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:
us...@infra.apache.org


With regards,
Apache Git Services

Reply via email to