{"action":"created","comment":{"url":"https://api.github.com/repos/apache/couchdb-documentation/pulls/comments/179886705","pull_request_review_id":110211394,"id":179886705,"diff_hunk":"@@ -18,43 +18,170 @@ Sharding\n \n .. _cluster/sharding/scaling-out:\n \n-Scaling out\n-===========\n+Introduction\n+------------\n \n-Normally you start small and grow over time. In the beginning you might do just\n-fine with one node, but as your data and number of clients grows, you need to\n-scale out.\n+A\n+`shard <https://en.wikipedia.org/wiki/Shard_(database_architecture)>`__\n+is a horizontal partition of data in a database. Partitioning data into\n+shards and distributing copies of each shard (called \"replicas\") to\n+different nodes in a cluster gives the data greater durability against\n+node loss. CouchDB clusters automatically shard and distribute data\n+among nodes, but modifying cluster membership and customizing shard\n+behavior must be done manually.\n \n-For simplicity we will start fresh and small.\n+Shards and Replicas\n+~~~~~~~~~~~~~~~~~~~\n \n-Start ``node1`` and add a database to it. To keep it simple we will have 2\n-shards and no replicas.\n+How many shards and replicas each database has can be set at the global\n+level, or on a per-database basis. The relevant parameters are *q* and\n+*n*.\n \n-.. code-block:: bash\n+*q* is the number of database shards to maintain. *n* is the number of\n+copies of each document to distribute. With q=8, the database is split\n+into 8 shards. With n=3, the cluster distributes three replicas of each\n+shard. Altogether, that's 24 shards for a single database. In a default\n+3-node cluster, each node would receive 8 shards. In a 4-node cluster,\n+each node would receive 6 shards.\n \n-    curl -X PUT \"http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2\" --user daboss\n+CouchDB nodes have a ``etc/default.ini`` file with a section named\n+``[cluster]`` which looks like this:\n \n-If you look in the directory ``data/shards`` you will find the 2 shards.\n+::\n \n-.. code-block:: text\n+    [cluster]\n+    q=8\n+    n=3\n \n-    data/\n-    +-- shards/\n-    |   +-- 00000000-7fffffff/\n-    |   |    -- small.1425202577.couch\n-    |   +-- 80000000-ffffffff/\n-    |        -- small.1425202577.couch\n+These settings can be modified to set sharding defaults for all\n+databases, or they can be set on a per-database basis by specifying the\n+``q`` and ``n`` query parameters when the database is created. For\n+example:\n \n-Now, check the node-local ``_dbs_`` database. Here, the metadata for each\n-database is stored. As the database is called ``small``, there is a document\n-called ``small`` there. Let us look in it. Yes, you can get it with curl too:\n+.. code:: bash\n \n-.. code-block:: javascript\n+    $ curl -X PUT \"$COUCH_URL/database-name?q=4&n=2\"\n \n-    curl -X GET \"http://xxx.xxx.xxx.xxx:5986/_dbs/small\"\n+That creates a database that is split into 4 shards and 2 replicas,\n+yielding 8 shards distributed throughout the cluster.\n+\n+Quorum\n+------\n+\n+When a CouchDB cluster serves reads and writes, it proxies the request\n+to nodes with relevant shards and responds once enough nodes have\n+responded to establish\n+`quorum <https://en.wikipedia.org/wiki/Quorum_(distributed_computing)>`__.\n+The size of the required quorum can be configured at request time by\n+setting the ``r`` parameter for document and view reads, and the ``w``\n+parameter for document writes. For example, here is a request that\n+specifies that at least two nodes must respond in order to establish\n+quorum:\n+\n+.. code:: bash\n+\n+    $ curl \"$COUCH_URL:5984/{docId}?r=2\"\n+\n+Here is a similar example for writing a document:\n+\n+.. code:: bash\n+\n+    $ curl -X PUT \"$COUCH_URL:5984/{docId}?w=2\" -d '{}'\n+\n+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)\n+means you will only receive a response once all nodes with relevant\n+shards have responded, however even this does not guarantee `ACIDic\n+consistency <https://en.wikipedia.org/wiki/ACID#Consistency>`__. Setting\n+``r`` or ``w`` to 1 means you will receive a response after only one\n+relevant node has responded.\n+\n+Adding a node\n+-------------\n+\n+To add a node to a cluster, first you must have the additional node\n+running somewhere. Make note of the address it binds to, like\n+``127.0.0.1``, then ``PUT`` an empty document to the ``/_node``","path":"src/cluster/sharding.rst","position":109,"original_position":109,"commit_id":"d6db5c4d287dd4b512fc404603162bb0d584ad01","original_commit_id":"d6db5c4d287dd4b512fc404603162bb0d584ad01","user":{"login":"wohali","id":112292,"avatar_url":"https://avatars2.githubusercontent.com/u/112292?v=4","gravatar_id":"","url":"https://api.github.com/users/wohali","html_url":"https://github.com/wohali","followers_url":"https://api.github.com/users/wohali/followers","following_url":"https://api.github.com/users/wohali/following{/other_user}","gists_url":"https://api.github.com/users/wohali/gists{/gist_id}","starred_url":"https://api.github.com/users/wohali/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/wohali/subscriptions","organizations_url":"https://api.github.com/users/wohali/orgs","repos_url":"https://api.github.com/users/wohali/repos","events_url":"https://api.github.com/users/wohali/events{/privacy}","received_events_url":"https://api.github.com/users/wohali/received_events","type":"User","site_admin":false},"body":"I'd use a domain name in an actual cluster; running multiple nodes on the same host kind-of defeats the purpose of a cluster and is only really done in dev/demo environments.","created_at":"2018-04-06T22:05:34Z","updated_at":"2018-04-06T22:13:28Z","html_url":"https://github.com/apache/couchdb-documentation/pull/268#discussion_r179886705","pull_request_url":"https://api.github.com/repos/apache/couchdb-documentation/pulls/268","author_association":"MEMBER","_links":{"self":{"href":"https://api.github.com/repos/apache/couchdb-documentation/pulls/comments/179886705"},"html":{"href":"https://github.com/apache/couchdb-documentation/pull/268#discussion_r179886705"},"pull_request":{"href":"https://api.github.com/repos/apache/couchdb-documentation/pulls/268"}}},"pull_request":{"url":"https://api.github.com/repos/apache/couchdb-documentation/pulls/268","id":180028184,"html_url":"https://github.com/apache/couchdb-documentation/pull/268","diff_url":"https://github.com/apache/couchdb-documentation/pull/268.diff","patch_url":"https://github.com/apache/couchdb-documentation/pull/268.patch","issue_url":"https://api.github.com/repos/apache/couchdb-documentation/issues/268","number":268,"state":"open","locked":false,"title":"Rewrite sharding documentation","user":{"login":"garbados","id":883103,"avatar_url":"https://avatars0.githubusercontent.com/u/883103?v=4","gravatar_id":"","url":"https://api.github.com/users/garbados","html_url":"https://github.com/garbados","followers_url":"https://api.github.com/users/garbados/followers","following_url":"https://api.github.com/users/garbados/following{/other_user}","gists_url":"https://api.github.com/users/garbados/gists{/gist_id}","starred_url":"https://api.github.com/users/garbados/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/garbados/subscriptions","organizations_url":"https://api.github.com/users/garbados/orgs","repos_url":"https://api.github.com/users/garbados/repos","events_url":"https://api.github.com/users/garbados/events{/privacy}","received_events_url":"https://api.github.com/users/garbados/received_events","type":"User","site_admin":false},"body":"<!-- Thank you for your contribution!\r\n\r\n     Please file this form by replacing the Markdown comments\r\n     with your text. If a section needs no action - remove it.\r\n\r\n     Also remember, that CouchDB uses the Review-Then-Commit (RTC) model\r\n     of code collaboration. Positive feedback is represented +1 from committers\r\n     and negative is a -1. The -1 also means veto, and needs to be addressed\r\n     to proceed. Once there are no objections, the PR can be merged by a\r\n     CouchDB committer.\r\n\r\n     See: http://couchdb.apache.org/bylaws.html#decisions for more info. -->\r\n\r\n## Overview\r\n\r\n<!-- Please give a short brief for the pull request,\r\n     what problem it solves or how it makes things better. -->\r\n\r\nThis WIP PR attempts to revisit the documentation on sharding to make it clearer, and to include detailed instructions for adding and removing nodes and shards.\r\n\r\n## Checklist\r\n\r\n- [x] Documentation is written and is accurate;\r\n- [x] `make check` passes with no errors\r\n- [ ] Update [rebar.config.script](https://github.com/apache/couchdb/blob/master/rebar.config.script) with the commit hash once this PR is rebased and merged\r\n","created_at":"2018-04-06T18:59:07Z","updated_at":"2018-04-06T22:13:28Z","closed_at":null,"merged_at":null,"merge_commit_sha":"dcd1c214d540652aa69c43804f2a7aa48bfffc1a","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[{"id":893180184,"url":"https://api.github.com/repos/apache/couchdb-documentation/labels/wip","name":"wip","color":"61ddaa","default":false}],"milestone":null,"commits_url":"https://api.github.com/repos/apache/couchdb-documentation/pulls/268/commits","review_comments_url":"https://api.github.com/repos/apache/couchdb-documentation/pulls/268/comments","review_comment_url":"https://api.github.com/repos/apache/couchdb-documentation/pulls/comments{/number}","comments_url":"https://api.github.com/repos/apache/couchdb-documentation/issues/268/comments","statuses_url":"https://api.github.com/repos/apache/couchdb-documentation/statuses/d6db5c4d287dd4b512fc404603162bb0d584ad01","head":{"label":"garbados:update-sharding-docs","ref":"update-sharding-docs","sha":"d6db5c4d287dd4b512fc404603162bb0d584ad01","user":{"login":"garbados","id":883103,"avatar_url":"https://avatars0.githubusercontent.com/u/883103?v=4","gravatar_id":"","url":"https://api.github.com/users/garbados","html_url":"https://github.com/garbados","followers_url":"https://api.github.com/users/garbados/followers","following_url":"https://api.github.com/users/garbados/following{/other_user}","gists_url":"https://api.github.com/users/garbados/gists{/gist_id}","starred_url":"https://api.github.com/users/garbados/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/garbados/subscriptions","organizations_url":"https://api.github.com/users/garbados/orgs","repos_url":"https://api.github.com/users/garbados/repos","events_url":"https://api.github.com/users/garbados/events{/privacy}","received_events_url":"https://api.github.com/users/garbados/received_events","type":"User","site_admin":false},"repo":{"id":105791067,"name":"couchdb-documentation","full_name":"garbados/couchdb-documentation","owner":{"login":"garbados","id":883103,"avatar_url":"https://avatars0.githubusercontent.com/u/883103?v=4","gravatar_id":"","url":"https://api.github.com/users/garbados","html_url":"https://github.com/garbados","followers_url":"https://api.github.com/users/garbados/followers","following_url":"https://api.github.com/users/garbados/following{/other_user}","gists_url":"https://api.github.com/users/garbados/gists{/gist_id}","starred_url":"https://api.github.com/users/garbados/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/garbados/subscriptions","organizations_url":"https://api.github.com/users/garbados/orgs","repos_url":"https://api.github.com/users/garbados/repos","events_url":"https://api.github.com/users/garbados/events{/privacy}","received_events_url":"https://api.github.com/users/garbados/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/garbados/couchdb-documentation","description":"Apache CouchDB Documentation","fork":true,"url":"https://api.github.com/repos/garbados/couchdb-documentation","forks_url":"https://api.github.com/repos/garbados/couchdb-documentation/forks","keys_url":"https://api.github.com/repos/garbados/couchdb-documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/garbados/couchdb-documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/garbados/couchdb-documentation/teams","hooks_url":"https://api.github.com/repos/garbados/couchdb-documentation/hooks","issue_events_url":"https://api.github.com/repos/garbados/couchdb-documentation/issues/events{/number}","events_url":"https://api.github.com/repos/garbados/couchdb-documentation/events","assignees_url":"https://api.github.com/repos/garbados/couchdb-documentation/assignees{/user}","branches_url":"https://api.github.com/repos/garbados/couchdb-documentation/branches{/branch}","tags_url":"https://api.github.com/repos/garbados/couchdb-documentation/tags","blobs_url":"https://api.github.com/repos/garbados/couchdb-documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/garbados/couchdb-documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/garbados/couchdb-documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/garbados/couchdb-documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/garbados/couchdb-documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/garbados/couchdb-documentation/languages","stargazers_url":"https://api.github.com/repos/garbados/couchdb-documentation/stargazers","contributors_url":"https://api.github.com/repos/garbados/couchdb-documentation/contributors","subscribers_url":"https://api.github.com/repos/garbados/couchdb-documentation/subscribers","subscription_url":"https://api.github.com/repos/garbados/couchdb-documentation/subscription","commits_url":"https://api.github.com/repos/garbados/couchdb-documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/garbados/couchdb-documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/garbados/couchdb-documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/garbados/couchdb-documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/garbados/couchdb-documentation/contents/{+path}","compare_url":"https://api.github.com/repos/garbados/couchdb-documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/garbados/couchdb-documentation/merges","archive_url":"https://api.github.com/repos/garbados/couchdb-documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/garbados/couchdb-documentation/downloads","issues_url":"https://api.github.com/repos/garbados/couchdb-documentation/issues{/number}","pulls_url":"https://api.github.com/repos/garbados/couchdb-documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/garbados/couchdb-documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/garbados/couchdb-documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/garbados/couchdb-documentation/labels{/name}","releases_url":"https://api.github.com/repos/garbados/couchdb-documentation/releases{/id}","deployments_url":"https://api.github.com/repos/garbados/couchdb-documentation/deployments","created_at":"2017-10-04T16:26:46Z","updated_at":"2017-10-04T16:26:49Z","pushed_at":"2018-04-06T21:51:34Z","git_url":"git://github.com/garbados/couchdb-documentation.git","ssh_url":"git@github.com:garbados/couchdb-documentation.git","clone_url":"https://github.com/garbados/couchdb-documentation.git","svn_url":"https://github.com/garbados/couchdb-documentation","homepage":"","size":5047,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":0,"license":null,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"apache:master","ref":"master","sha":"a1b2fcdf09f78c4bca9b6c3c9bc57014220fcbf9","user":{"login":"apache","id":47359,"avatar_url":"https://avatars0.githubusercontent.com/u/47359?v=4","gravatar_id":"","url":"https://api.github.com/users/apache","html_url":"https://github.com/apache","followers_url":"https://api.github.com/users/apache/followers","following_url":"https://api.github.com/users/apache/following{/other_user}","gists_url":"https://api.github.com/users/apache/gists{/gist_id}","starred_url":"https://api.github.com/users/apache/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apache/subscriptions","organizations_url":"https://api.github.com/users/apache/orgs","repos_url":"https://api.github.com/users/apache/repos","events_url":"https://api.github.com/users/apache/events{/privacy}","received_events_url":"https://api.github.com/users/apache/received_events","type":"Organization","site_admin":false},"repo":{"id":15993609,"name":"couchdb-documentation","full_name":"apache/couchdb-documentation","owner":{"login":"apache","id":47359,"avatar_url":"https://avatars0.githubusercontent.com/u/47359?v=4","gravatar_id":"","url":"https://api.github.com/users/apache","html_url":"https://github.com/apache","followers_url":"https://api.github.com/users/apache/followers","following_url":"https://api.github.com/users/apache/following{/other_user}","gists_url":"https://api.github.com/users/apache/gists{/gist_id}","starred_url":"https://api.github.com/users/apache/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apache/subscriptions","organizations_url":"https://api.github.com/users/apache/orgs","repos_url":"https://api.github.com/users/apache/repos","events_url":"https://api.github.com/users/apache/events{/privacy}","received_events_url":"https://api.github.com/users/apache/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/apache/couchdb-documentation","description":"Apache CouchDB Documentation","fork":false,"url":"https://api.github.com/repos/apache/couchdb-documentation","forks_url":"https://api.github.com/repos/apache/couchdb-documentation/forks","keys_url":"https://api.github.com/repos/apache/couchdb-documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/apache/couchdb-documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/apache/couchdb-documentation/teams","hooks_url":"https://api.github.com/repos/apache/couchdb-documentation/hooks","issue_events_url":"https://api.github.com/repos/apache/couchdb-documentation/issues/events{/number}","events_url":"https://api.github.com/repos/apache/couchdb-documentation/events","assignees_url":"https://api.github.com/repos/apache/couchdb-documentation/assignees{/user}","branches_url":"https://api.github.com/repos/apache/couchdb-documentation/branches{/branch}","tags_url":"https://api.github.com/repos/apache/couchdb-documentation/tags","blobs_url":"https://api.github.com/repos/apache/couchdb-documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/apache/couchdb-documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/apache/couchdb-documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/apache/couchdb-documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/apache/couchdb-documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/apache/couchdb-documentation/languages","stargazers_url":"https://api.github.com/repos/apache/couchdb-documentation/stargazers","contributors_url":"https://api.github.com/repos/apache/couchdb-documentation/contributors","subscribers_url":"https://api.github.com/repos/apache/couchdb-documentation/subscribers","subscription_url":"https://api.github.com/repos/apache/couchdb-documentation/subscription","commits_url":"https://api.github.com/repos/apache/couchdb-documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/apache/couchdb-documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/apache/couchdb-documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/apache/couchdb-documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/apache/couchdb-documentation/contents/{+path}","compare_url":"https://api.github.com/repos/apache/couchdb-documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/apache/couchdb-documentation/merges","archive_url":"https://api.github.com/repos/apache/couchdb-documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/apache/couchdb-documentation/downloads","issues_url":"https://api.github.com/repos/apache/couchdb-documentation/issues{/number}","pulls_url":"https://api.github.com/repos/apache/couchdb-documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/apache/couchdb-documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/apache/couchdb-documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/apache/couchdb-documentation/labels{/name}","releases_url":"https://api.github.com/repos/apache/couchdb-documentation/releases{/id}","deployments_url":"https://api.github.com/repos/apache/couchdb-documentation/deployments","created_at":"2014-01-17T08:00:08Z","updated_at":"2018-04-06T11:26:04Z","pushed_at":"2018-04-06T21:51:36Z","git_url":"git://github.com/apache/couchdb-documentation.git","ssh_url":"git@github.com:apache/couchdb-documentation.git","clone_url":"https://github.com/apache/couchdb-documentation.git","svn_url":"https://github.com/apache/couchdb-documentation","homepage":"","size":5044,"stargazers_count":52,"watchers_count":52,"language":"Python","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":100,"mirror_url":null,"archived":false,"open_issues_count":9,"license":{"key":"apache-2.0","name":"Apache License 2.0","spdx_id":"Apache-2.0","url":"https://api.github.com/licenses/apache-2.0"},"forks":100,"open_issues":9,"watchers":52,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/apache/couchdb-documentation/pulls/268"},"html":{"href":"https://github.com/apache/couchdb-documentation/pull/268"},"issue":{"href":"https://api.github.com/repos/apache/couchdb-documentation/issues/268"},"comments":{"href":"https://api.github.com/repos/apache/couchdb-documentation/issues/268/comments"},"review_comments":{"href":"https://api.github.com/repos/apache/couchdb-documentation/pulls/268/comments"},"review_comment":{"href":"https://api.github.com/repos/apache/couchdb-documentation/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/apache/couchdb-documentation/pulls/268/commits"},"statuses":{"href":"https://api.github.com/repos/apache/couchdb-documentation/statuses/d6db5c4d287dd4b512fc404603162bb0d584ad01"}},"author_association":"CONTRIBUTOR"}}
{"actor":{"display_login":"wohali"}}