flimzy commented on a change in pull request #268: Rewrite sharding
documentation
URL:
https://github.com/apache/couchdb-documentation/pull/268#discussion_r179913724
##########
File path: src/cluster/sharding.rst
##########
@@ -97,27 +224,49 @@ called ``small`` there. Let us look in it. Yes, you can
get it with curl too:
}
}
-* ``_id`` The name of the database.
-* ``_rev`` The current revision of the metadata.
-* ``shard_suffix`` The numbers after small and before .couch. This is seconds
- after UNIX epoch when the database was created. Stored as ASCII characters.
-* ``changelog`` Self explaining. Mostly used for debugging.
-* ``by_node`` List of shards on each node.
-* ``by_range`` On which nodes each shard is.
+Here is a brief anatomy of that document:
+
+- ``_id``: The name of the database.
+- ``_rev``: The current revision of the metadata.
+- ``shard_suffix``: A timestamp of the database's creation, marked as
+ seconds after the Unix epoch mapped to the codepoints for ASCII
+ numerals.
+- ``changelog``: History of the database's shards.
+- ``by_node``: List of shards on each node.
+- ``by_range``: On which nodes each shard is.
+
+To reflect the shard move in the metadata, there are three steps:
+
+1. Add appropriate changelog entries.
+2. Update the ``by_node`` entries.
+3. Update the ``by_range`` entries.
+
+As of this writing, this process must be done manually. **WARNING: Be
+very careful! Mistakes during this process can irreperably corrupt the
+cluster!**
-Nothing here, nothing there, a shard in my sleeve
--------------------------------------------------
+To add a shard to a node, add entries like this to the database
+metadata's ``changelog`` attribute:
-Start node2 and add it to the cluster. Check in ``/_membership`` that the
-nodes are talking with each other.
+.. code:: json
-If you look in the directory ``data`` on node2, you will see that there is no
-directory called shards.
+ [
+ "add",
+ "{range}",
+ "{name}@{address}"
+ ]
-Use curl to change the ``_dbs/small`` node-local document for small, so it
-looks like this:
+*Note*: You can remove a node by specifying 'remove' instead of 'add'.
-.. code-block:: javascript
+Once you have figured out the new changelog entries, you will need to
+update the ``by_node`` and ``by_range`` to reflect who is storing what
+shards. The data in the changelog entries and these attributes must
+match. If they do not, the database may become corrupted.
+
+As an example, here is an updated version of the metadata above that
+adds shards to a second node called ``node2``:
+
+.. code:: json
{
"_id": "small",
Review comment:
Do you want to rename this `small` to `{name}` for consistency, as well?
----------------------------------------------------------------
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
