wohali commented on a change in pull request #268: Rewrite sharding
documentation
URL:
https://github.com/apache/couchdb-documentation/pull/268#discussion_r203230201
##########
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:
+
+.. code:: bash
+
+ # delete the file
+ rm $COUCH_DIR/data/shards/$OLD_SHARD
-When you get to ``n=3`` you should start moving the shards instead of adding
-more replicas.
+ # OR delete the database
+ curl -X DELETE $COUCH_URL:5986/$OLD_SHARD
-We will stop on ``n=2`` to keep things simple. Start node number 3 and add it
to
-the cluster. Then create the directories for the shard on node3:
+Congratulations! You have manually added a new shard. By adding and
+removing database shards in this way, they can be moved between nodes.
-.. code-block:: bash
+Specifying database placement
+-----------------------------
- mkdir -p data/shards/00000000-7fffffff
+Database shards can be configured to live solely on specific nodes using
+placement rules.
-And copy over ``data/shards/00000000-7fffffff/small.1425202577.couch`` from
-node1 to node3. Do not move files between the shard directories as that will
-confuse CouchDB!
+First, each node must be labeled with a zone attribute. This defines
+which zone each node is in. You do this by editing the node’s document
+in the ``/nodes`` database, which is accessed through the “back-door”
+(5986) port. Add a key value pair of the form:
-Edit the database document in ``_dbs`` again. Make it so that node3 have a
-replica of the shard ``00000000-7fffffff``. Save the document and let CouchDB
-sync. If we do not do this, then writes made during the copy of the shard and
-the updating of the metadata will only have ``n=1`` until CouchDB has synced.
+::
-Then update the metadata document so that node2 no longer have the shard
-``00000000-7fffffff``. You can now safely delete
-``data/shards/00000000-7fffffff/small.1425202577.couch`` on node 2.
+ "zone": "{zone-name}"
-The changelog is nothing that CouchDB cares about, it is only for the admins.
-But for the sake of completeness, we will update it again. Use ``delete`` for
-recording the removal of the shard ``00000000-7fffffff`` from node2.
+Do this for all of the nodes in your cluster. For example:
-Start node4, add it to the cluster and do the same as above with shard
-``80000000-ffffffff``.
+.. code:: bash
-All documents added during this operation was saved and all reads responded to
-without the users noticing anything.
+ $ curl -X PUT $COUCH_URL:5986/_nodes/{name}@{address} \
+ -d '{ \
+ "_id": "{name}@{address}",
+ "_rev": "{rev}",
+ "zone": "{zone-name}"
+ }'
-.. _cluster/sharding/views:
+In the config file (local.ini or default.ini) of each node, define a
+consistent cluster-wide setting like:
-Views
-=====
+::
-The views need to be moved together with the shards. If you do not, then
-CouchDB will rebuild them and this will take time if you have a lot of
-documents.
+ [cluster]
+ placement = {zone-name-1}:2,{zone-name-2}:1
-The views are stored in ``data/.shards``.
+In this example, it will ensure that two replicas for a shard will be
+hosted on nodes with the zone attribute set to ``{zone-name-1}`` and one
+replica will be hosted on a new with the zone attribute set to
+``{zone-name-2}``.
-It is possible to not move the views and let CouchDB rebuild the view every
-time you move a shard. As this can take quite some time, it is not recommended.
+Note that you can also use this system to ensure certain nodes in the
+cluster do not host any replicas for newly created databases, by giving
+them a zone attribute that does not appear in the ``[cluster]``
+placement string.
-.. _cluster/sharding/preshard:
+You can also specify zones on a per-database basis by specifying the
+zone as a query parameter when the database is created:
-Reshard? No, Preshard!
-======================
+.. code:: bash
-Reshard? Nope. It cannot be done. So do not create databases with too few
-shards.
+ curl -X PUT $COUCH_URL:5984/{dbName}?zone={zone}
-If you can not scale out more because you set the number of shards too low,
then
-you need to create a new cluster and migrate over.
+Resharding
+----------
-#. Build a cluster with enough nodes to handle one copy of your data.
-#. Create a database with the same name, n=1 and with enough shards so you do
- not have to do this again.
-#. Set up 2 way replication between the 2 clusters.
-#. Let it sync.
-#. Tell clients to use both the clusters.
-#. Add some nodes to the new cluster and add them as replicas.
-#. Remove some nodes from the old cluster.
-#. Repeat 6 and 7 until you have enough nodes in the new cluster to have 3
- replicas of every shard.
-#. Redirect all clients to the new cluster
-#. Turn off the 2 way replication between the clusters.
-#. Shut down the old cluster and add the servers as new nodes to the new
- cluster.
-#. Relax!
+Shard settings for databases can only be set when the database is
+created, precluding live resharding. Instead, to reshard a database, it
+must be regenerated. Here are the steps:
-Creating more shards than you need and then move the shards around is called
-presharding. The number of shards you need depends on how much data you are
-going to store. But, creating too many shards increases the complexity without
-any real gain. You might even get lower performance. As an example of this, we
Review comment:
On second thought, "presharding" is more related to the concept of CouchDB's
sharding in general - we pre-shard databases, meaning we don't re-shard a
database after its creation, we decide at creation time where shards go.
Anyway, let's not get into specific recommendations without community
consensus. Starting a thread on user@ or dev@ asking for sharding advice based
on DB size, doc size, etc. would probably be a good first step.
----------------------------------------------------------------
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
