[GitHub] janl commented on issue #1105: Fauxton build broken on Windows

[GitBox]

janl commented on issue #1105: Fauxton build broken on Windows
URL: 
https://github.com/apache/couchdb-fauxton/issues/1105#issuecomment-406172278
 
 
   @wohali do you still have more of that log. Would be good to see what part 
of the npm install process it was in when this happened.
   


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

[Jenkins] FAILURE: CouchDB » master #308

[Apache Jenkins Server]

Boo, we failed. https://builds.apache.org/job/CouchDB/job/master/308/

[Jenkins] FAILURE: CouchDB » master #309

[Apache Jenkins Server]

Boo, we failed. https://builds.apache.org/job/CouchDB/job/master/309/

[GitHub] Antonio-Maranhao commented on issue #1105: Fauxton build broken on Windows

[GitBox]

Antonio-Maranhao commented on issue #1105: Fauxton build broken on Windows
URL: 
https://github.com/apache/couchdb-fauxton/issues/1105#issuecomment-406127229
 
 
   @wohali I tried on a Windows 10 VM and didn't find any issues. Note I didn't 
run a couchdb build. I simply ran the two commands from 
https://github.com/apache/couchdb/blob/master/Makefile.win#L333
   
   ```
   C:\relax\couchdb-fauxton>npm install --production
   npm WARN The package less is included as both a dev and production 
dependency.
   npm WARN The package less-loader is included as both a dev and production 
dependency.
   npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.1.3 
(node_modules\webpack\node_modules\fsevents):
   npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for 
fsevents@1.1.3: wanted {"os":"darwin","arch":"any"} (current: 
{"os":"win32","arch":"x64"})
   npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.1.3 
(node_modules\webpack-dev-server\node_modules\fsevents):
   npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for 
fsevents@1.1.3: wanted {"os":"darwin","arch":"any"} (current: 
{"os":"win32","arch":"x64"})
   npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.1.3 
(node_modules\babel-cli\node_modules\fsevents):
   npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for 
fsevents@1.1.3: wanted {"os":"darwin","arch":"any"} (current: 
{"os":"win32","arch":"x64"})
   
   added 2190 packages from 883 contributors and audited 14243 packages in 
103.249s
   found 477 vulnerabilities (337 low, 111 moderate, 27 high, 2 critical)
 run `npm audit fix` to fix them, or `npm audit` for details
   
   C:\relax\couchdb-fauxton>.\node_modules\.bin\grunt couchdb
   Running "clean:release" (clean) task
   >> 1 path cleaned.
   
   Running "get_deps:default" (get_deps) task
   Fetching external dependencies
   0 local dependencies
   
   Running "gen_load_addons:default" (gen_load_addons) task
   
   Running "gen_initialize:release" (gen_initialize) task
   
   Running "copy:distDepsRequire" (copy) task
   Created 12 directories, copied 218 files
   
   Running "shell:webpackrelease" (shell) task
   
   > fauxton@1.1.15 webpack:release C:\relax\couchdb-fauxton
   > webpack --optimize-minimize --debug --progress --colors --config 
./webpack.config.release.js
   
   Hash: 3abfb7dab79ea7a53cd3
   Version: webpack 2.2.1
   Time: 72658ms
  Asset Size  Chunks
Chunk Names
dashboard.assets/fonts/fauxtonicon5.ttf  19.4 kB  
[emitted]
  dashboard.assets/img/asf-feather-logo.png23 kB  
[emitted]
dashboard.assets/img/github.png  4.27 kB  
[emitted]
dashboard.assets/img/googleplus.png  3.64 kB  
[emitted]
  dashboard.assets/img/linkedin.png  1.99 kB  
[emitted]
   dashboard.assets/img/twitter.png  32.5 kB  
[emitted]
   dashboard.assets/img/couch-watermark.png   2.1 kB  
[emitted]
dashboard.assets/fonts/fauxtonicon5.eot  19.6 kB  
[emitted]
  dashboard.assets/img/fauxtonicon5.svg   130 kB  
[emitted]
 dashboard.assets/fonts/fontawesome-webfont.eot  37.4 kB  
[emitted]
dashboard.assets/img/loader.gif  5.19 kB  
[emitted]
  dashboard.assets/img/couchdb-logo.png   3.1 kB  
[emitted]
 dashboard.assets/fonts/fontawesome-webfont.ttf  79.1 kB  
[emitted]
   dashboard.assets/fonts/fauxtonicon5.woff  11.2 kB  
[emitted]
dashboard.assets/fonts/fontawesome-webfont.woff  43.6 kB  
[emitted]
   dashboard.assets/img/fontawesome-webfont.svg   198 kB  
[emitted]
 dashboard.assets/img/CouchDB-negative-logo.png14 kB  
[emitted]
 dashboard.assets/js/vendor.1ece90de5402e75ffaf4.js  1.73 MB0, 2  
[emitted]  [big]  vendor
 dashboard.assets/js/bundle.dfdb82af612bf7a4d8eb.js   658 kB1, 2  
[emitted]  [big]  bundle
   dashboard.assets/js/manifest.ea148358c7d895bfa49e.js  1.45 kB   2  
[emitted] manifest
   dashboard.assets/css/styles.dfdb82af612bf7a4d8eb.css   229 kB1, 2  
[emitted] bundle
 index.html  1.98 kB  
[emitted]
  [0] ./~/react/index.js 190 bytes {0} [built]
 [11] ./app/app.js 2.95 kB {1} [built]
 [22] ./~/react-redux/es/index.js 230 bytes {0} [built]
 [40] ./~/core-js/modules/_core.js 122 bytes {0} [built]
 [72] ./~/backbone/backbone.js 115 bytes {0} [built]
[468] ./~/redux/es/redux.js 22.8 kB {0} [built]
[476] ./app/main.js 3.98 kB {1} [built]
[477] ./~/core-js/fn/array/index.js 1.15 kB {0} [built]
[478] ./~/core-js/fn/object/index.js 1.48 kB {0} [built]
[479] ./~/core-js/fn/promise.js 298 byt

[GitHub] wohali commented on issue #1449: Fix the Windows build

[GitBox]

wohali commented on issue #1449: Fix the Windows build
URL: https://github.com/apache/couchdb/issues/1449#issuecomment-406058892
 
 
   Building without Fauxton, all CouchDB tests now pass. \o/


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

[GitHub] wohali closed issue #1449: Fix the Windows build

[GitBox]

wohali closed issue #1449: Fix the Windows build
URL: https://github.com/apache/couchdb/issues/1449
 
 
   


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

[GitHub] Antonio-Maranhao closed pull request #1106: Fix how local creds are checked when creating replications

[GitBox]

Antonio-Maranhao closed pull request #1106: Fix how local creds are checked 
when creating replications
URL: https://github.com/apache/couchdb-fauxton/pull/1106
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/app/addons/replication/components/newreplication.js 
b/app/addons/replication/components/newreplication.js
index 8a1fd7f05..38ca807b5 100644
--- a/app/addons/replication/components/newreplication.js
+++ b/app/addons/replication/components/newreplication.js
@@ -12,7 +12,7 @@
 
 import base64 from 'base-64';
 import React from 'react';
-import app from '../../../app';
+import Helpers from '../../../helpers';
 import {json} from '../../../core/ajax';
 import FauxtonAPI from '../../../core/api';
 import {ReplicationSource} from './source';
@@ -101,7 +101,7 @@ export default class NewReplicationController extends 
React.Component {
   }
 
   checkCredentials(username, password) {
-return json(app.host + '/', 'GET', {
+return json(Helpers.getServerUrl('/'), 'GET', {
   credentials: 'omit',
   headers: {
 'Authorization':'Basic ' + base64.encode(username + ':' + password)


 


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

[GitHub] Antonio-Maranhao commented on issue #1106: Fix how local creds are checked when creating replications

[GitBox]

Antonio-Maranhao commented on issue #1106: Fix how local creds are checked when 
creating replications
URL: https://github.com/apache/couchdb-fauxton/pull/1106#issuecomment-406048973
 
 
   @popojargo no worries - my mistake as well for not double checking other 
uses of `app.host`. 
   There's only one left in `addons/setup/base.js` which I assume it's related 
to the issue you already mentioned.
   Thanks!


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

[GitHub] popojargo commented on issue #1106: Fix how local creds are checked when creating replications

[GitBox]

popojargo commented on issue #1106: Fix how local creds are checked when 
creating replications
URL: https://github.com/apache/couchdb-fauxton/pull/1106#issuecomment-406040360
 
 
   👍  if travis pass. I should have paid more attention to the PR after my 
relative url change.


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

[GitHub] Antonio-Maranhao commented on issue #1104: Please cut new Fauxton release (for CouchDB 2.2.0)

[GitBox]

Antonio-Maranhao commented on issue #1104: Please cut new Fauxton release (for 
CouchDB 2.2.0)
URL: 
https://github.com/apache/couchdb-fauxton/issues/1104#issuecomment-406038945
 
 
   @popojargo I spoke too soon - found an issue and here's a PR with the fix: 
https://github.com/apache/couchdb-fauxton/pull/1106


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

[GitHub] Antonio-Maranhao opened a new pull request #1106: Fix how local creds are checked when creating replications

[GitBox]

Antonio-Maranhao opened a new pull request #1106: Fix how local creds are 
checked when creating replications
URL: https://github.com/apache/couchdb-fauxton/pull/1106
 
 
   ## Overview
   
   When creating/editing replications, the code for credentials check is using 
`app.host` directly which is not a problem in the dev environment, but it 
produces errors in the release build.
   
   ## Testing recommendations
   
   - Create a new replication using local a database with user/password as 
either source or target.
   - The replication is created successfully
   
   ## Checklist
   
   - [x] Code is written and works correctly;
   - [x] Changes are covered by tests;
   - [ ] Documentation reflects the changes;
   - [ ] Update 
[rebar.config.script](https://github.com/apache/couchdb/blob/master/rebar.config.script)
 with the correct tag once a new Fauxton release is made
   


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

[GitHub] wohali commented on issue #1449: Fix the Windows build

[GitBox]

wohali commented on issue #1449: Fix the Windows build
URL: https://github.com/apache/couchdb/issues/1449#issuecomment-406036182
 
 
   bcrypt has been removed, now this is holding things up:
   
   https://github.com/apache/couchdb-fauxton/issues/1105
   
   /cc @popojargo @Antonio-Maranhao 


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

[GitHub] wohali opened a new issue #1105: Fauxton build broken on Windows

[GitBox]

wohali opened a new issue #1105: Fauxton build broken on Windows
URL: https://github.com/apache/couchdb-fauxton/issues/1105
 
 
   HI there,
   
   Attempting to build the current `master` version of Fauxton on Windows is 
failing:
   
   ```
   "Building Fauxton"
   npm WARN The package less is included as both a dev and production 
dependency.
   npm WARN The package less-loader is included as both a dev and production 
dependency.
   
   npm ERR! Cannot read property '0' of undefined
   
   npm ERR! A complete log of this run can be found in:
   npm ERR! 
C:\Users\wohali\AppData\Roaming\npm-cache\_logs\2018-07-18T18_45_34_805Z-debug.log
   make: *** [share\www] Error 1
   
   C:\relax\couchdb>node --version
   v10.6.0
   
   C:\relax\couchdb>npm --version
   6.1.0
   ```
   
   The relevant excerpt from `debug.log` follows:
   
   ```
   1255 warn The package less is included as both a dev and production 
dependency.
   1256 warn The package less-loader is included as both a dev and production 
dependency.
   1257 verbose stack TypeError: Cannot read property '0' of undefined
   1257 verbose stack at rmStuff (C:\Program 
Files\nodejs\node_modules\npm\lib\unbuild.js:61:24)
   1257 verbose stack at tryCatcher (C:\Program 
Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\util.js:16:23)
   1257 verbose stack at ret (eval at makeNodePromisifiedEval (C:\Program 
Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promisify.js:184:12),
 :13:39)
   1257 verbose stack at lifecycle.then.then (C:\Program 
Files\nodejs\node_modules\npm\lib\install\action\unbuild.js:12:12)
   1257 verbose stack at tryCatcher (C:\Program 
Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\util.js:16:23)
   1257 verbose stack at Promise._settlePromiseFromHandler (C:\Program 
Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise.js:512:31)
   1257 verbose stack at Promise._settlePromise (C:\Program 
Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise.js:569:18)
   1257 verbose stack at Promise._settlePromise0 (C:\Program 
Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise.js:614:10)
   1257 verbose stack at Promise._settlePromises (C:\Program 
Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise.js:693:18)
   1257 verbose stack at Promise._fulfill (C:\Program 
Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise.js:638:18)
   1257 verbose stack at C:\Program 
Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\nodeback.js:42:21
   1258 verbose cwd C:\relax\couchdb\src\fauxton
   1259 verbose Windows_NT 10.0.15063
   1260 verbose argv "C:\\Program Files\\nodejs\\node.exe" "C:\\Program 
Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install" "--production"
   1261 verbose node v10.6.0
   1262 verbose npm  v6.1.0
   1263 error Cannot read property '0' of undefined
   1264 verbose exit [ 1, true ]
   ```


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

[GitHub] wohali commented on issue #1105: Fauxton build broken on Windows

[GitBox]

wohali commented on issue #1105: Fauxton build broken on Windows
URL: 
https://github.com/apache/couchdb-fauxton/issues/1105#issuecomment-406035569
 
 
   Just as a note I tried this initially on v8.1.3 of node, then upgraded to 
v10.6 to see if it'd fix the problem - it didn't.


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

[GitHub] garrensmith commented on issue #1423: Mango to nodes

[GitBox]

garrensmith commented on issue #1423: Mango to nodes
URL: https://github.com/apache/couchdb/pull/1423#issuecomment-406031589
 
 
   @davisp I was expecting much better performance. I'm happy to park this PR 
for now. I think it would be useful for when we look at mango aggregation. So 
we can either close this PR or keep it open for a bit. 
   
   I'll revisit it once we get around to mango aggregations.


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

[GitHub] wohali closed pull request #1457: Remove bcrypt implementation

[GitBox]

wohali closed pull request #1457: Remove bcrypt implementation
URL: https://github.com/apache/couchdb/pull/1457
 
 
   


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

[GitHub] wohali commented on issue #297: Configure cluster Erlang port range using vm.args

[GitBox]

wohali commented on issue #297: Configure cluster Erlang port range using 
vm.args
URL: 
https://github.com/apache/couchdb-documentation/pull/297#issuecomment-406022477
 
 
   Thank you for the important fix, @d3alek ! And welcome to the CouchDB 
contributor community! :tada: 


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

[GitHub] wohali closed pull request #297: Configure cluster Erlang port range using vm.args

[GitBox]

wohali closed pull request #297: Configure cluster Erlang port range using 
vm.args
URL: https://github.com/apache/couchdb-documentation/pull/297
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/src/cluster/setup.rst b/src/cluster/setup.rst
index d7fb40f..683062f 100644
--- a/src/cluster/setup.rst
+++ b/src/cluster/setup.rst
@@ -119,31 +119,16 @@ To close the shells, run in both:
 Make CouchDB use the open ports.
 
 
-Open ``sys.config``, on all nodes, and add ``inet_dist_listen_min, 9100`` and
-``inet_dist_listen_max, 9200`` like below:
+Open ``vm.args``, on all nodes, and add ``-kernel inet_dist_listen_min 9100``
+and ``-kernel inet_dist_listen_max 9200`` like below:
 
 .. code-block:: erlang
 
-[
-{lager, [
-{error_logger_hwm, 1000},
-{error_logger_redirect, true},
-{handlers, [
-{lager_console_backend, [debug, {
-lager_default_formatter,
-[
-date, " ", time,
-" [", severity, "] ",
-node, " ", pid, " ",
-message,
-"\n"
-]
-}]}
-]},
-{inet_dist_listen_min, 9100},
-{inet_dist_listen_max, 9200}
-]}
-].
+-name ...
+-setcookie ...
+...
+-kernel inet_dist_listen_max 9100
+-kernel inet_dist_listen_max 9200
 
 .. _cluster/setup/wizard:
 


 


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

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
 
 Review comm

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
 Review comment:
   I added something to this effect:
   
   > This document discusses how sharding works in CouchDB along with how to
   > safely add, move, remove, and create placement rules for shards and
   > shard replicas.


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

[GitHub] garbados commented on issue #268: Rewrite sharding documentation

[GitBox]

garbados commented on issue #268: Rewrite sharding documentation
URL: 
https://github.com/apache/couchdb-documentation/pull/268#issuecomment-406019440
 
 
   I added a new commit that responds to a lot of the feedback folks left. I'll 
respond to the outstanding comments that remain so I can figure out any 
additional changes it needs.


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

[Jenkins] SUCCESS: CouchDB » master #307

[Apache Jenkins Server]

Yay, we passed. https://builds.apache.org/job/CouchDB/job/master/307/

[GitHub] wohali closed pull request #1456: bump hyper dependency, fix Windows build

[GitBox]

wohali closed pull request #1456: bump hyper dependency, fix Windows build
URL: https://github.com/apache/couchdb/pull/1456
 
 
   


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

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+-

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+-

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+--

[GitHub] wohali opened a new pull request #1457: Remove bcrypt implementation

[GitBox]

wohali opened a new pull request #1457: Remove bcrypt implementation
URL: https://github.com/apache/couchdb/pull/1457
 
 
   As per our desire to get 2.2.0 out as soon as possible, this commit reverts 
addition of bcrypt functionality, originally contributed in #1212, and the 
subsequent related PRs #1231 and #1258.
   
   I will +1 bringing this back into CouchDB after the 2.2.0 release, once the 
issues described in #1455 can be addressed.
   
   I have +1s from @rnewson and @janl to do this, so as long as the build 
passes, I will merge this PR.


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

[GitHub] wohali commented on issue #1455: Re-introduce support for bcrypt

[GitBox]

wohali commented on issue #1455: Re-introduce support for bcrypt
URL: https://github.com/apache/couchdb/issues/1455#issuecomment-405990494
 
 
   The `bcrypt` branch has been restored, and has cherry-picked commits on it 
for all of the merged PRs that improved its test suite.
   
   Feel free to use this for work going forward, or if a rewrite is needed, 
reimplement from scratch.


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

[GitHub] wohali commented on issue #1160: Add support for Bcrypt password hashing

[GitBox]

wohali commented on issue #1160: Add support for Bcrypt password hashing
URL: https://github.com/apache/couchdb/pull/1160#issuecomment-405989634
 
 
   The new issue is at https://github.com/apache/couchdb/issues/1455


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

[GitHub] wohali commented on issue #1449: Fix the Windows build

[GitBox]

wohali commented on issue #1449: Fix the Windows build
URL: https://github.com/apache/couchdb/issues/1449#issuecomment-405989532
 
 
   https://github.com/apache/couchdb/pull/1456 will fix the hyper issue.
   
   Backing `bcrypt` out of master with +1s from  @rnewson and @janl, see 
https://github.com/apache/couchdb/pull/1160#issuecomment-405986847


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

[GitHub] wohali opened a new pull request #1456: bump hyper dependency, fix Windows build

[GitBox]

wohali opened a new pull request #1456: bump hyper dependency, fix Windows build
URL: https://github.com/apache/couchdb/pull/1456
 
 
   Helps with #1346 .


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

[GitHub] davisp commented on issue #1423: Mango to nodes

[GitBox]

davisp commented on issue #1423: Mango to nodes
URL: https://github.com/apache/couchdb/pull/1423#issuecomment-405989096
 
 
   From what I see there's basically no difference. For the network traffic 
graphs it looks maybe a bit less on the front end but then spikes badly on the 
second half. And if memory serves you were attempting to have a best case 
scenario for this test by restricting results to an empty set. Given there's 
not a dramatic difference I'm hesitant on whether this change is actually 
providing any benefit.
   
   The regression tests I think are even more indicative of this not having 
much if any effect on the results. Your largest median change on a single test 
is only 23ms and it looks like nearly half of them are measuring nearly exactly 
the same suggesting this PR isn't providing a measurable difference.
   
   Can you describe the tests you did for the network graphs? Perhaps we missed 
something there or we can figure out how to measure things better?


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

[GitHub] wohali closed pull request #4: Fix hyper build for Windows

[GitBox]

wohali closed pull request #4: Fix hyper build for Windows
URL: https://github.com/apache/couchdb-hyper/pull/4
 
 
   


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

[GitHub] wohali opened a new issue #1455: Re-introduce support for bcrypt

[GitBox]

wohali opened a new issue #1455: Re-introduce support for bcrypt
URL: https://github.com/apache/couchdb/issues/1455
 
 
   In preparing the 2.2.0 release, it was found that the bcrypt add-on will not 
compile under Windows. There are at least 2 reasons for this:
   
   1. Windows does not include the BSD libc extensions, meaning there is no 
`sys/queue.h`.
   1. Our Windows build environment, which does not use msys/mingw/etc, does 
not have a useful pthread library.
   
   In addition, it seems wrong to me that a NIF to just run an encryption 
routine is launching its own threads. Threading and scheduling of those threads 
should be left up to the Erlang interpreter.
   
   Because of the level of integration of bcrypt, it is not feasible to remove 
the library on one platform, or at configure time. An attempt to do that by 
@iilyak was aborted, see #1228.
   
   As such, the `bcrypt` application is being removed from master.
   
   ## Expected Behavior
   `bcrypt` functionality should be restored to CouchDB post-2.2.0. That 
reworked implementation should work under Windows, and should not rely on 
pthreads.
   
   ## Current Behavior
   Windows build is broken, full stop.


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

[GitHub] wohali commented on issue #1160: Add support for Bcrypt password hashing

[GitBox]

wohali commented on issue #1160: Add support for Bcrypt password hashing
URL: https://github.com/apache/couchdb/pull/1160#issuecomment-405986847
 
 
   @pierrekilly @janl unfortunately bcrypt is terminally broken on Windows, as 
it is missing the BSD libc extensions (queue.h) and a useful pthreads 
implementation.
   
   Further, it seems to me that it makes no sense for our NIF to link to a 
function that is, itself, launching pthreads. Surely this will wreak havoc with 
the Erlang scheduler? /cc @davisp 
   
   I am unfortunately going to have to remove this functionality to unblock the 
2.2 release for now, as we can't hold up the release waiting for a rewrite. 
   
   I have restored the `bcrypt` branch so that work can be ongoing for this in 
a future release. I will attempt to cherry-pick any bcrypt changes that landed 
post-`bcrypt` to that branch as a convenience.
   
   Since both PRs have landed, I will open a new ticket for this issue to track 
work going forward.


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

[GitHub] iilyak commented on issue #1432: Support callback module data provider

[GitBox]

iilyak commented on issue #1432: Support callback module data provider
URL: https://github.com/apache/couchdb/pull/1432#issuecomment-405975884
 
 
   > @iilyak is there a strong motivation to merge it for 2.2.0?
   
   @wohali: We can wait. It is a bug fix for a feature which is not used yet. 


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

[GitHub] wohali commented on issue #1449: Fix the Windows build

[GitBox]

wohali commented on issue #1449: Fix the Windows build
URL: https://github.com/apache/couchdb/issues/1449#issuecomment-405973123
 
 
   Partially addressed by https://github.com/apache/couchdb-hyper/pull/4
   
   Turns out `bcrypt` won't compile now, that's the next 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

[GitHub] wohali opened a new pull request #4: Fix hyper build for Windows

[GitBox]

wohali opened a new pull request #4: Fix hyper build for Windows
URL: https://github.com/apache/couchdb-hyper/pull/4
 
 
   This PR works around missing C99 features for the Windows build environment, 
as well as necessarily fixes an attempt at pointer arithmetic with `void *`.


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

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+-

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
 
 Review comment:
   You're right, it should read "subset" of documents. I'll update it 
accordingly.


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

[GitHub] Antonio-Maranhao commented on issue #1104: Please cut new Fauxton release (for CouchDB 2.2.0)

[GitBox]

Antonio-Maranhao commented on issue #1104: Please cut new Fauxton release (for 
CouchDB 2.2.0)
URL: 
https://github.com/apache/couchdb-fauxton/issues/1104#issuecomment-405961397
 
 
   @popojargo FYI I've tested everything besides Setup and didn't find any 
other issues. 
   


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

[GitHub] d3alek opened a new pull request #297: Configure cluster Erlang port range using vm.args

[GitBox]

d3alek opened a new pull request #297: Configure cluster Erlang port range 
using vm.args
URL: https://github.com/apache/couchdb-documentation/pull/297
 
 
   Ports specified in sys.config as per previous documentation seem to be 
ignored by CouchDB
   
   ## Overview
   
   Current documentation suggests putting the distributed Erlang port range 
restriction in `sys.config`, however in my experience this does not get picked 
up by CouchDB. What works for me is specifying the port range in `vm.args` 
instead.  I am using a recent build from source (`62f71c0b0`).
   
   I am aware I may not be putting `sys.config` in the correct place to be 
picked up by CouchDB - if that's the case and modifying `sys.config` works for 
you then let me know and I will change the PR to simply clarify the correct 
location for `sys.config`. 
   
   ## Testing recommendations
   
   ## GitHub issue number
   
   ## Related Pull Requests
   
   ## Checklist
   
   - [x ] Documentation is written and is accurate;
   - [x ] `make check` passes with no errors
   - [ ] 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
   


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

[GitHub] garrensmith commented on issue #1423: Mango to nodes

[GitBox]

garrensmith commented on issue #1423: Mango to nodes
URL: https://github.com/apache/couchdb/pull/1423#issuecomment-405954505
 
 
   I've run some perf tests on this. First a very basic performance test. Below 
are metrics for network traffic between nodes. The first image is for current 
mango. The second image is CouchDB with this PR.
   
![old-mango2](https://user-images.githubusercontent.com/179458/42888527-c1c0a704-8aa8-11e8-9e25-bfebbcb3e02d.png)
   
   
   
![new-mango2](https://user-images.githubusercontent.com/179458/42888561-ce4197a4-8aa8-11e8-8253-8e383f4c61d4.png)
   
   The graphs are not at the same scale which is a bit frustrating. There is no 
regression and a slight improvement on network traffic. 
   Then I ran a full regression test:
   
![regression-test](https://user-images.githubusercontent.com/179458/42888648-f9729112-8aa8-11e8-9daf-3e6371548f23.png)
   
   There are no regressions and in some cases a nice performance improvement.
   


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

[GitHub] popojargo commented on issue #1104: Please cut new Fauxton release (for CouchDB 2.2.0)

[GitBox]

popojargo commented on issue #1104: Please cut new Fauxton release (for CouchDB 
2.2.0)
URL: 
https://github.com/apache/couchdb-fauxton/issues/1104#issuecomment-405953101
 
 
   If necessary, reverting this PR would be a better idea IMO since it's not an 
improvement, only a refactor.


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

[GitHub] garrensmith commented on a change in pull request #1425: Add `conflicts: true` option to mango selectors

[GitBox]

garrensmith commented on a change in pull request #1425: Add `conflicts: true` 
option to mango selectors
URL: https://github.com/apache/couchdb/pull/1425#discussion_r203393704
 
 

 ##
 File path: src/mango/test/19-find-conflicts.py
 ##
 @@ -0,0 +1,41 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+import mango
+import copy
+
+DOC = [
+{
+"_id": "doc",
+"a": 2
+}
+]
+
+CONFLICT = [
+{
+"_id": "doc",
+"_rev": "1-23202479633c2b380f79507a776743d5",
+"a": 1
+}
+]
+
+class ChooseCorrectIndexForDocs(mango.DbPerClass):
+def setUp(self):
+self.db.recreate()
+self.db.save_docs(copy.deepcopy(DOC))
+self.db.save_docs_with_conflicts(copy.deepcopy(CONFLICT))
+
+def test_retrieve_conflicts(self):
+self.db.create_index(["_conflicts"])
 
 Review comment:
   This test doesn't need this index since it won't actually use it with an 
`$exists` query.


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

[GitHub] wohali commented on issue #1104: Please cut new Fauxton release (for CouchDB 2.2.0)

[GitBox]

wohali commented on issue #1104: Please cut new Fauxton release (for CouchDB 
2.2.0)
URL: 
https://github.com/apache/couchdb-fauxton/issues/1104#issuecomment-405939398
 
 
   If necessary, feel free to cut a release just prior to that commit if you 
can't fix the problem rapidly.


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203383179
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
+
+This is set in the default.ini file located here::
+
+/etc/couchdb/default.ini
+
+If you've installed from source and are running CouchDB in dev mode the log
+files are located here::
+
+YOUR-COUCHDB-SOURCE-DIRECTORY/tmp/log/couch.log
+
+How do I use transactions with CouchDB?
+---
+
+CouchDB uses an "optimistic concurrency" model. In the simplest terms, this
+just means that you send a document version along with your update, and CouchDB
+rejects the change if the current document version doesn't match what you've
+sent.
+
+It's deceptively simple, really. You can reframe many normal transaction based
+scenarios for CouchDB. You do need to sort of throw out your RDBMS domain
+knowledge when learning CouchDB, though. It's helpful to approach problems from
+a higher level, rather than attempting to mold Couch to a SQL based world.
+
+**Keeping track of inventory**
+
+The problem you outlined is primarily an inventory issue. If you have a 
document
+describing an item, and it includes a field for "quantity available", you can
+handle concurrency issues like this:
+
+- Retrieve the document, take note of the `_rev` property that CouchDB sends
+  along
+- Decrement the quantity field, if it's greater than zero
+- Send the updated document back, using the `_rev` property
+- If the `_rev` matches the currently stored number, be done!
+- If there's a conflict (when `_rev` doesn't match), retrieve the newest
+  document version
+
+In this instance, there are two possible failure scenarios to think about. If
+the most recent document version has a quantity of 0, you handle it just like
+you would in a RDBMS and alert the user that they can't actually buy what they
+wanted to purchase. If the most recent document version has a quantity greater
+than 0, you simply repeat the operation with the updated data, and start back
+at the beginning. This forces you to do a bit more work than an RDBMS would, 
and
+could get a little annoying if there are frequent, conflicting updates.
+
+Now, the answer I just gave presupposes that you're going to do things in
+CouchDB in much the same way that you would in an RDBMS. I might approach this
+problem a bit differently:
+
+I'd start with a "master product" document that includes all the descriptor 
data
+(name, picture, description, price, etc). Then I'd add an "inventory ticket"
+document for each specific instance, with fields for product_key and 
claimed_by.
+If you're selling a model of hammer, and have 20 of them to sell, you might 
have
+documents with keys like hammer-1, hammer-2, etc, to represent each available
+hammer.
+
+Then, I'd create a view that gives me a list of available hammers, with a 
reduce
+function that lets me see a "total". These are completely off the cuff, but
+should give you an idea of what a working view would look like.
+
+**Map**::
+
+function(doc)
+{
+if (doc.type == 'inventory_ticket' && doc.claimed_by == null ) {
+emit(doc.product_key, { 'inventory_ticket' :doc.id, '_rev' : 
doc._rev });
+}
+}
+
+This gives me a list of available "tickets", by product key. I could grab a
+group of these when someone wants to buy a hammer, then iterate through sending
+updates (using the id and _rev) until I successfully claim one (previously
+claimed tickets will result in an update error).
+
+**Reduce**::
+
+function (keys, values, combine) {
+return values.length;
+}
+
+This reduce function simply returns the total number of unclaimed
+inventory_ticket items, so you can tell how many "hammers" are available for
+purchase.
+
+**Caveats**
+
+This solution represents roughly 3.5 minutes of total thinking for the
+particular problem you've presented. There may be better ways of doing this!
+That said, it does substantially reduce conflicting updates, and cuts down on
+the need to respond to a conflict

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203384991
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
+
+This is set in the default.ini file located here::
+
+/etc/couchdb/default.ini
+
+If you've installed from source and are running CouchDB in dev mode the log
+files are located here::
+
+YOUR-COUCHDB-SOURCE-DIRECTORY/tmp/log/couch.log
+
+How do I use transactions with CouchDB?
+---
+
+CouchDB uses an "optimistic concurrency" model. In the simplest terms, this
+just means that you send a document version along with your update, and CouchDB
+rejects the change if the current document version doesn't match what you've
+sent.
+
+It's deceptively simple, really. You can reframe many normal transaction based
+scenarios for CouchDB. You do need to sort of throw out your RDBMS domain
+knowledge when learning CouchDB, though. It's helpful to approach problems from
+a higher level, rather than attempting to mold Couch to a SQL based world.
+
+**Keeping track of inventory**
+
+The problem you outlined is primarily an inventory issue. If you have a 
document
+describing an item, and it includes a field for "quantity available", you can
+handle concurrency issues like this:
+
+- Retrieve the document, take note of the `_rev` property that CouchDB sends
+  along
+- Decrement the quantity field, if it's greater than zero
+- Send the updated document back, using the `_rev` property
+- If the `_rev` matches the currently stored number, be done!
+- If there's a conflict (when `_rev` doesn't match), retrieve the newest
+  document version
+
+In this instance, there are two possible failure scenarios to think about. If
+the most recent document version has a quantity of 0, you handle it just like
+you would in a RDBMS and alert the user that they can't actually buy what they
+wanted to purchase. If the most recent document version has a quantity greater
+than 0, you simply repeat the operation with the updated data, and start back
+at the beginning. This forces you to do a bit more work than an RDBMS would, 
and
+could get a little annoying if there are frequent, conflicting updates.
+
+Now, the answer I just gave presupposes that you're going to do things in
+CouchDB in much the same way that you would in an RDBMS. I might approach this
+problem a bit differently:
+
+I'd start with a "master product" document that includes all the descriptor 
data
+(name, picture, description, price, etc). Then I'd add an "inventory ticket"
+document for each specific instance, with fields for product_key and 
claimed_by.
+If you're selling a model of hammer, and have 20 of them to sell, you might 
have
+documents with keys like hammer-1, hammer-2, etc, to represent each available
+hammer.
+
+Then, I'd create a view that gives me a list of available hammers, with a 
reduce
+function that lets me see a "total". These are completely off the cuff, but
+should give you an idea of what a working view would look like.
+
+**Map**::
+
+function(doc)
+{
+if (doc.type == 'inventory_ticket' && doc.claimed_by == null ) {
+emit(doc.product_key, { 'inventory_ticket' :doc.id, '_rev' : 
doc._rev });
+}
+}
+
+This gives me a list of available "tickets", by product key. I could grab a
+group of these when someone wants to buy a hammer, then iterate through sending
+updates (using the id and _rev) until I successfully claim one (previously
+claimed tickets will result in an update error).
+
+**Reduce**::
+
+function (keys, values, combine) {
+return values.length;
+}
+
+This reduce function simply returns the total number of unclaimed
+inventory_ticket items, so you can tell how many "hammers" are available for
+purchase.
+
+**Caveats**
+
+This solution represents roughly 3.5 minutes of total thinking for the
+particular problem you've presented. There may be better ways of doing this!
+That said, it does substantially reduce conflicting updates, and cuts down on
+the need to respond to a conflict

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203380098
 
 

 ##
 File path: src/faq/documents.rst
 ##
 @@ -0,0 +1,35 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/documents:
+
+=
+Documents
+=
+
+Why use _bulk_docs instead of PUTting single documents to CouchDB?
+--
+
+Aside from the HTTP overhead and roundtrip you are saving, the main advantage 
is
+that CouchDB can handle the B-tree updates more efficiently, decreasing
+rewriting of intermediary and parent nodes, both improving speed and saving 
disk
+space.
+
+Why can't I use MVCC in CouchDB as a revision control system for my docs?
+-
+
+The revisions CouchDB stores for each document are removed when the database is
+compacted. The database may be compacted at any time by a DB admin to save hard
+drive space. If you were using those revisions for document versioning, you'd
+lose them all upon compaction. In addition, your disk usage would grow with
+every document iteration and (if you prevented database compaction) you'd have
+no way to recover the used disk space.
 
 Review comment:
   + "If you want to keep all versions of some data, you can store them as 
separate CouchDB documents, or use attachments to store just the previous 
revisions you care about to a newly created version."


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203380733
 
 

 ##
 File path: src/faq/howto.rst
 ##
 @@ -0,0 +1,22 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/howto:
+
+===
+How-Tos
+===
+
+How can I get a list of the design documents in a database?
+---
+
+Query the `_all_docs` view with `startkey="_design/"&endkey="_design0"`.
 
 Review comment:
   We have a new `/_design_docs` endpoint, recommend that instead. It should be 
documented - and the FAQ should link to the documentation for the endpoint. If 
it's not documented, file a bug.


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203381059
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
+
+This is set in the default.ini file located here::
+
+/etc/couchdb/default.ini
 
 Review comment:
   No longer the right location, this is now under 
`/opt/couchdb/etc/default.ini`.


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203383602
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
+
+This is set in the default.ini file located here::
+
+/etc/couchdb/default.ini
+
+If you've installed from source and are running CouchDB in dev mode the log
+files are located here::
+
+YOUR-COUCHDB-SOURCE-DIRECTORY/tmp/log/couch.log
+
+How do I use transactions with CouchDB?
+---
+
+CouchDB uses an "optimistic concurrency" model. In the simplest terms, this
+just means that you send a document version along with your update, and CouchDB
+rejects the change if the current document version doesn't match what you've
+sent.
+
+It's deceptively simple, really. You can reframe many normal transaction based
+scenarios for CouchDB. You do need to sort of throw out your RDBMS domain
+knowledge when learning CouchDB, though. It's helpful to approach problems from
+a higher level, rather than attempting to mold Couch to a SQL based world.
+
+**Keeping track of inventory**
+
+The problem you outlined is primarily an inventory issue. If you have a 
document
+describing an item, and it includes a field for "quantity available", you can
+handle concurrency issues like this:
+
+- Retrieve the document, take note of the `_rev` property that CouchDB sends
+  along
+- Decrement the quantity field, if it's greater than zero
+- Send the updated document back, using the `_rev` property
+- If the `_rev` matches the currently stored number, be done!
+- If there's a conflict (when `_rev` doesn't match), retrieve the newest
+  document version
+
+In this instance, there are two possible failure scenarios to think about. If
+the most recent document version has a quantity of 0, you handle it just like
+you would in a RDBMS and alert the user that they can't actually buy what they
+wanted to purchase. If the most recent document version has a quantity greater
+than 0, you simply repeat the operation with the updated data, and start back
+at the beginning. This forces you to do a bit more work than an RDBMS would, 
and
+could get a little annoying if there are frequent, conflicting updates.
+
+Now, the answer I just gave presupposes that you're going to do things in
+CouchDB in much the same way that you would in an RDBMS. I might approach this
+problem a bit differently:
+
+I'd start with a "master product" document that includes all the descriptor 
data
+(name, picture, description, price, etc). Then I'd add an "inventory ticket"
+document for each specific instance, with fields for product_key and 
claimed_by.
+If you're selling a model of hammer, and have 20 of them to sell, you might 
have
+documents with keys like hammer-1, hammer-2, etc, to represent each available
+hammer.
+
+Then, I'd create a view that gives me a list of available hammers, with a 
reduce
+function that lets me see a "total". These are completely off the cuff, but
+should give you an idea of what a working view would look like.
+
+**Map**::
+
+function(doc)
+{
+if (doc.type == 'inventory_ticket' && doc.claimed_by == null ) {
+emit(doc.product_key, { 'inventory_ticket' :doc.id, '_rev' : 
doc._rev });
+}
+}
+
+This gives me a list of available "tickets", by product key. I could grab a
+group of these when someone wants to buy a hammer, then iterate through sending
+updates (using the id and _rev) until I successfully claim one (previously
+claimed tickets will result in an update error).
+
+**Reduce**::
+
+function (keys, values, combine) {
+return values.length;
+}
+
+This reduce function simply returns the total number of unclaimed
+inventory_ticket items, so you can tell how many "hammers" are available for
+purchase.
+
+**Caveats**
+
+This solution represents roughly 3.5 minutes of total thinking for the
+particular problem you've presented. There may be better ways of doing this!
+That said, it does substantially reduce conflicting updates, and cuts down on
+the need to respond to a conflict

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203381511
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
+
+This is set in the default.ini file located here::
+
+/etc/couchdb/default.ini
+
+If you've installed from source and are running CouchDB in dev mode the log
+files are located here::
+
+YOUR-COUCHDB-SOURCE-DIRECTORY/tmp/log/couch.log
 
 Review comment:
   Also no longer true.
   
   If you've installed from source and are running CouchDB with the developer 
`dev/run` utility, log files are under the `dev/logs` directory.


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203383763
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
+
+This is set in the default.ini file located here::
+
+/etc/couchdb/default.ini
+
+If you've installed from source and are running CouchDB in dev mode the log
+files are located here::
+
+YOUR-COUCHDB-SOURCE-DIRECTORY/tmp/log/couch.log
+
+How do I use transactions with CouchDB?
+---
+
+CouchDB uses an "optimistic concurrency" model. In the simplest terms, this
+just means that you send a document version along with your update, and CouchDB
+rejects the change if the current document version doesn't match what you've
+sent.
+
+It's deceptively simple, really. You can reframe many normal transaction based
+scenarios for CouchDB. You do need to sort of throw out your RDBMS domain
+knowledge when learning CouchDB, though. It's helpful to approach problems from
+a higher level, rather than attempting to mold Couch to a SQL based world.
+
+**Keeping track of inventory**
+
+The problem you outlined is primarily an inventory issue. If you have a 
document
+describing an item, and it includes a field for "quantity available", you can
+handle concurrency issues like this:
+
+- Retrieve the document, take note of the `_rev` property that CouchDB sends
+  along
+- Decrement the quantity field, if it's greater than zero
+- Send the updated document back, using the `_rev` property
+- If the `_rev` matches the currently stored number, be done!
+- If there's a conflict (when `_rev` doesn't match), retrieve the newest
+  document version
+
+In this instance, there are two possible failure scenarios to think about. If
+the most recent document version has a quantity of 0, you handle it just like
+you would in a RDBMS and alert the user that they can't actually buy what they
+wanted to purchase. If the most recent document version has a quantity greater
+than 0, you simply repeat the operation with the updated data, and start back
+at the beginning. This forces you to do a bit more work than an RDBMS would, 
and
+could get a little annoying if there are frequent, conflicting updates.
+
+Now, the answer I just gave presupposes that you're going to do things in
+CouchDB in much the same way that you would in an RDBMS. I might approach this
+problem a bit differently:
+
+I'd start with a "master product" document that includes all the descriptor 
data
+(name, picture, description, price, etc). Then I'd add an "inventory ticket"
+document for each specific instance, with fields for product_key and 
claimed_by.
+If you're selling a model of hammer, and have 20 of them to sell, you might 
have
+documents with keys like hammer-1, hammer-2, etc, to represent each available
+hammer.
+
+Then, I'd create a view that gives me a list of available hammers, with a 
reduce
+function that lets me see a "total". These are completely off the cuff, but
+should give you an idea of what a working view would look like.
+
+**Map**::
+
+function(doc)
+{
+if (doc.type == 'inventory_ticket' && doc.claimed_by == null ) {
+emit(doc.product_key, { 'inventory_ticket' :doc.id, '_rev' : 
doc._rev });
+}
+}
+
+This gives me a list of available "tickets", by product key. I could grab a
+group of these when someone wants to buy a hammer, then iterate through sending
+updates (using the id and _rev) until I successfully claim one (previously
+claimed tickets will result in an update error).
+
+**Reduce**::
+
+function (keys, values, combine) {
+return values.length;
+}
+
+This reduce function simply returns the total number of unclaimed
+inventory_ticket items, so you can tell how many "hammers" are available for
+purchase.
+
+**Caveats**
+
+This solution represents roughly 3.5 minutes of total thinking for the
+particular problem you've presented. There may be better ways of doing this!
+That said, it does substantially reduce conflicting updates, and cuts down on
+the need to respond to a conflict

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203380195
 
 

 ##
 File path: src/faq/general.rst
 ##
 @@ -0,0 +1,55 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/general:
+
+===
+General
+===
+
+What is CouchDB?
+
+
+CouchDB is a document-oriented, NoSQL_ database. The
+:ref:`Introduction ` provides a high level overview of the
+CouchDB system.
+
+.. _NoSQL: https://en.wikipedia.org/wiki/NoSQL
+
+What does "Couch" mean?
+---
+
+"Couch" is an acronym which stands for **C**\ luster **O**\ f **U**\ nreliable
 
 Review comment:
   backronym, actually :)


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203385352
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
 
 Review comment:
   There is an entire Troubleshooting section elsewhere in the documentation, 
this entire document should merge with it.


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203380363
 
 

 ##
 File path: src/faq/general.rst
 ##
 @@ -0,0 +1,55 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/general:
+
+===
+General
+===
+
+What is CouchDB?
+
+
+CouchDB is a document-oriented, NoSQL_ database. The
+:ref:`Introduction ` provides a high level overview of the
+CouchDB system.
+
+.. _NoSQL: https://en.wikipedia.org/wiki/NoSQL
+
+What does "Couch" mean?
+---
+
+"Couch" is an acronym which stands for **C**\ luster **O**\ f **U**\ nreliable
+**C**\ ommodity **H**\ ardware. This is a statement of Couch's long-term goal 
of
+massive scalability and high reliability on fault-prone hardware. The
+distributed nature and flat address space of the database will enable node
 
 Review comment:
   "enables" not "will enable," this is a vagary of the 1.x approach showing up 
in this FAQ


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203380519
 
 

 ##
 File path: src/faq/general.rst
 ##
 @@ -0,0 +1,55 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/general:
 
 Review comment:
   These are so general purpose that I feel like they should be answered in 
Chapter 1 of the docs, rather than in a FAQ. It might be best to strike this 
entire .rst file.


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203379714
 
 

 ##
 File path: src/faq/documents.rst
 ##
 @@ -0,0 +1,35 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/documents:
+
+=
+Documents
+=
+
+Why use _bulk_docs instead of PUTting single documents to CouchDB?
+--
+
+Aside from the HTTP overhead and roundtrip you are saving, the main advantage 
is
+that CouchDB can handle the B-tree updates more efficiently, decreasing
+rewriting of intermediary and parent nodes, both improving speed and saving 
disk
+space.
+
+Why can't I use MVCC in CouchDB as a revision control system for my docs?
+-
+
+The revisions CouchDB stores for each document are removed when the database is
+compacted. The database may be compacted at any time by a DB admin to save hard
+drive space. If you were using those revisions for document versioning, you'd
 
 Review comment:
   `drive space and improve performance.`


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203379293
 
 

 ##
 File path: src/faq/capabilities.rst
 ##
 @@ -0,0 +1,48 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/capabilities:
+
+
+Capabilities
+
+
+What platforms are supported?
+-
+
+- Most POSIX systems, including GNU/Linux, OS X and FreeBSD.
+- Windows is officially supported.
+
+How much stuff can I store in CouchDB?
+--
+
+The database size is primarily limited by resource limitations of your hardware
+and operating system. with node partitioning, this can be increased 
drastically,
+to be virtually unlimited.
+
+Can I talk to CouchDB without going through the HTTP API?
+-
+
+CouchDB's data model and internal API map the REST/HTTP model so well that any
+other API would basically reinvent some flavor of HTTP. However, there is a
+plan to refactor CouchDB's internals so as to provide a documented Erlang API.
 
 Review comment:
   These plans never came to fruition, please drop this question


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203382830
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
+
+This is set in the default.ini file located here::
+
+/etc/couchdb/default.ini
+
+If you've installed from source and are running CouchDB in dev mode the log
+files are located here::
+
+YOUR-COUCHDB-SOURCE-DIRECTORY/tmp/log/couch.log
+
+How do I use transactions with CouchDB?
 
 Review comment:
   I like the spirit of this example but it has some bad practices in it for 
2.x, including using JS views (Mango is faster and easier to set up), emission 
of the document ID and rev (which are always in the output of a view anyway, 
use of the first person (who is talking?), and doesn't explain why a reduce is 
necessary or what changes when you add a reduce to a JS view - amongst other 
smaller complaints. It also says that it's an off-the-cuff response, which 
feels inappropriate within the context of official documentation.
   
   Personally I'd drop it as it stands. It's a common RDBMS question, though, 
and it makes me want to have somethign about this in the docs at some point.


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203385114
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
+
+This is set in the default.ini file located here::
+
+/etc/couchdb/default.ini
+
+If you've installed from source and are running CouchDB in dev mode the log
+files are located here::
+
+YOUR-COUCHDB-SOURCE-DIRECTORY/tmp/log/couch.log
+
+How do I use transactions with CouchDB?
+---
+
+CouchDB uses an "optimistic concurrency" model. In the simplest terms, this
+just means that you send a document version along with your update, and CouchDB
+rejects the change if the current document version doesn't match what you've
+sent.
+
+It's deceptively simple, really. You can reframe many normal transaction based
+scenarios for CouchDB. You do need to sort of throw out your RDBMS domain
+knowledge when learning CouchDB, though. It's helpful to approach problems from
+a higher level, rather than attempting to mold Couch to a SQL based world.
+
+**Keeping track of inventory**
+
+The problem you outlined is primarily an inventory issue. If you have a 
document
+describing an item, and it includes a field for "quantity available", you can
+handle concurrency issues like this:
+
+- Retrieve the document, take note of the `_rev` property that CouchDB sends
+  along
+- Decrement the quantity field, if it's greater than zero
+- Send the updated document back, using the `_rev` property
+- If the `_rev` matches the currently stored number, be done!
+- If there's a conflict (when `_rev` doesn't match), retrieve the newest
+  document version
+
+In this instance, there are two possible failure scenarios to think about. If
+the most recent document version has a quantity of 0, you handle it just like
+you would in a RDBMS and alert the user that they can't actually buy what they
+wanted to purchase. If the most recent document version has a quantity greater
+than 0, you simply repeat the operation with the updated data, and start back
+at the beginning. This forces you to do a bit more work than an RDBMS would, 
and
+could get a little annoying if there are frequent, conflicting updates.
+
+Now, the answer I just gave presupposes that you're going to do things in
+CouchDB in much the same way that you would in an RDBMS. I might approach this
+problem a bit differently:
+
+I'd start with a "master product" document that includes all the descriptor 
data
+(name, picture, description, price, etc). Then I'd add an "inventory ticket"
+document for each specific instance, with fields for product_key and 
claimed_by.
+If you're selling a model of hammer, and have 20 of them to sell, you might 
have
+documents with keys like hammer-1, hammer-2, etc, to represent each available
+hammer.
+
+Then, I'd create a view that gives me a list of available hammers, with a 
reduce
+function that lets me see a "total". These are completely off the cuff, but
+should give you an idea of what a working view would look like.
+
+**Map**::
+
+function(doc)
+{
+if (doc.type == 'inventory_ticket' && doc.claimed_by == null ) {
+emit(doc.product_key, { 'inventory_ticket' :doc.id, '_rev' : 
doc._rev });
+}
+}
+
+This gives me a list of available "tickets", by product key. I could grab a
+group of these when someone wants to buy a hammer, then iterate through sending
+updates (using the id and _rev) until I successfully claim one (previously
+claimed tickets will result in an update error).
+
+**Reduce**::
+
+function (keys, values, combine) {
+return values.length;
+}
+
+This reduce function simply returns the total number of unclaimed
+inventory_ticket items, so you can tell how many "hammers" are available for
+purchase.
+
+**Caveats**
+
+This solution represents roughly 3.5 minutes of total thinking for the
+particular problem you've presented. There may be better ways of doing this!
+That said, it does substantially reduce conflicting updates, and cuts down on
+the need to respond to a conflict

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203384538
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
+
+This is set in the default.ini file located here::
+
+/etc/couchdb/default.ini
+
+If you've installed from source and are running CouchDB in dev mode the log
+files are located here::
+
+YOUR-COUCHDB-SOURCE-DIRECTORY/tmp/log/couch.log
+
+How do I use transactions with CouchDB?
+---
+
+CouchDB uses an "optimistic concurrency" model. In the simplest terms, this
+just means that you send a document version along with your update, and CouchDB
+rejects the change if the current document version doesn't match what you've
+sent.
+
+It's deceptively simple, really. You can reframe many normal transaction based
+scenarios for CouchDB. You do need to sort of throw out your RDBMS domain
+knowledge when learning CouchDB, though. It's helpful to approach problems from
+a higher level, rather than attempting to mold Couch to a SQL based world.
+
+**Keeping track of inventory**
+
+The problem you outlined is primarily an inventory issue. If you have a 
document
+describing an item, and it includes a field for "quantity available", you can
+handle concurrency issues like this:
+
+- Retrieve the document, take note of the `_rev` property that CouchDB sends
+  along
+- Decrement the quantity field, if it's greater than zero
+- Send the updated document back, using the `_rev` property
+- If the `_rev` matches the currently stored number, be done!
+- If there's a conflict (when `_rev` doesn't match), retrieve the newest
+  document version
+
+In this instance, there are two possible failure scenarios to think about. If
+the most recent document version has a quantity of 0, you handle it just like
+you would in a RDBMS and alert the user that they can't actually buy what they
+wanted to purchase. If the most recent document version has a quantity greater
+than 0, you simply repeat the operation with the updated data, and start back
+at the beginning. This forces you to do a bit more work than an RDBMS would, 
and
+could get a little annoying if there are frequent, conflicting updates.
+
+Now, the answer I just gave presupposes that you're going to do things in
+CouchDB in much the same way that you would in an RDBMS. I might approach this
+problem a bit differently:
+
+I'd start with a "master product" document that includes all the descriptor 
data
+(name, picture, description, price, etc). Then I'd add an "inventory ticket"
+document for each specific instance, with fields for product_key and 
claimed_by.
+If you're selling a model of hammer, and have 20 of them to sell, you might 
have
+documents with keys like hammer-1, hammer-2, etc, to represent each available
+hammer.
+
+Then, I'd create a view that gives me a list of available hammers, with a 
reduce
+function that lets me see a "total". These are completely off the cuff, but
+should give you an idea of what a working view would look like.
+
+**Map**::
+
+function(doc)
+{
+if (doc.type == 'inventory_ticket' && doc.claimed_by == null ) {
+emit(doc.product_key, { 'inventory_ticket' :doc.id, '_rev' : 
doc._rev });
+}
+}
+
+This gives me a list of available "tickets", by product key. I could grab a
+group of these when someone wants to buy a hammer, then iterate through sending
+updates (using the id and _rev) until I successfully claim one (previously
+claimed tickets will result in an update error).
+
+**Reduce**::
+
+function (keys, values, combine) {
+return values.length;
+}
+
+This reduce function simply returns the total number of unclaimed
+inventory_ticket items, so you can tell how many "hammers" are available for
+purchase.
+
+**Caveats**
+
+This solution represents roughly 3.5 minutes of total thinking for the
+particular problem you've presented. There may be better ways of doing this!
+That said, it does substantially reduce conflicting updates, and cuts down on
+the need to respond to a conflict

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203380979
 
 

 ##
 File path: src/faq/troubleshooting.rst
 ##
 @@ -0,0 +1,222 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/troubleshooting:
+
+===
+Troubleshooting
+===
+
+Where are the CouchDB log files located?
+
+
+For a default Linux/Unix installation the log files are located here::
+
+/usr/local/var/log/couchdb/couch.log
 
 Review comment:
   No longer true, the standard **package-based** installation is 
`/var/log/couchdb/couch.log`.


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

[GitHub] wohali commented on a change in pull request #275: Add FAQ

[GitBox]

wohali commented on a change in pull request #275: Add FAQ
URL: 
https://github.com/apache/couchdb-documentation/pull/275#discussion_r203379654
 
 

 ##
 File path: src/faq/documents.rst
 ##
 @@ -0,0 +1,35 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _faq/documents:
+
+=
+Documents
+=
+
+Why use _bulk_docs instead of PUTting single documents to CouchDB?
+--
+
+Aside from the HTTP overhead and roundtrip you are saving, the main advantage 
is
+that CouchDB can handle the B-tree updates more efficiently, decreasing
+rewriting of intermediary and parent nodes, both improving speed and saving 
disk
+space.
+
+Why can't I use MVCC in CouchDB as a revision control system for my docs?
+-
+
+The revisions CouchDB stores for each document are removed when the database is
+compacted. The database may be compacted at any time by a DB admin to save hard
 
 Review comment:
   `...by the automatic compaction system or a DB admin`


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203384387
 
 

 ##
 File path: migration_6_to_7.md
 ##
 @@ -0,0 +1,97 @@
+# Migration Guide for moving from Nano 6.x to 7.x
+
+Version 7.0.0 saw a major switch in return values from the majority of Nano 
functions. The version 6 version of Nano always returned a 
[request](https://www.npmjs.com/package/request) object from any function call 
that made an HTTP/HTTPS request.
+
+
+In Nano 6:
+
+```js
+// Nano 6
+var db = nano.db.use('mydb')
+var x = db.get('mydoc') 
+// x is a request object
+```
+
+In Nano 7:
+
+```js
+// Nano 7
+var db = nano.db.use('mydb')
+var x = db.get('mydoc') 
 
 Review comment:
   👍 


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203384035
 
 

 ##
 File path: migration_6_to_7.md
 ##
 @@ -0,0 +1,97 @@
+# Migration Guide for moving from Nano 6.x to 7.x
+
+Version 7.0.0 saw a major switch in return values from the majority of Nano 
functions. The version 6 version of Nano always returned a 
[request](https://www.npmjs.com/package/request) object from any function call 
that made an HTTP/HTTPS request.
+
+
+In Nano 6:
+
+```js
+// Nano 6
+var db = nano.db.use('mydb')
+var x = db.get('mydoc') 
+// x is a request object
+```
+
+In Nano 7:
+
+```js
+// Nano 7
+var db = nano.db.use('mydb')
 
 Review comment:
   👍 


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203383193
 
 

 ##
 File path: lib/nano.js
 ##
 @@ -738,6 +825,25 @@ module.exports = exports = nano = function dbScope(cfg) {
   }, callback);
 }
 
+function insertAttAsStream(docName, attName, att, contentType, qs, 
callback) {
+  if (typeof qs === 'function') {
 
 Review comment:
   👍 done


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

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
 
 Review comment:
   "subsections of documents" sounds like sharding happens on a sub-document 
level. Is that true? (are attachments and documents sharded separately, for 
example?)  If so, is this clarified somewhere? Or should this read "subsets of 
documents"?


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

[GitHub] wohali commented on issue #268: Rewrite sharding documentation

[GitBox]

wohali commented on issue #268: Rewrite sharding documentation
URL: 
https://github.com/apache/couchdb-documentation/pull/268#issuecomment-405930565
 
 
   @mikerhodes @flimzy @willholley thanks for your help in reviewing this PR!
   
   I wanted to point out here that @garbados has done excellent work here 
writing this up, it's far better than what we had before, and that what we had 
here previously was in some ways dangerously bad advice. I hope that she sees 
your comments as constructive criticism, not dogpiling ;)
   
   I don't want your comments to hold up our getting this into the 2.2.0 
release. If any of your comments above can be skipped, or addressed in a 
subsequent PR, please make it known.


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

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
 Review comment:
   The Dynamo paper's primary example is n=3, but it doesn't go into why.


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

[GitHub] popojargo edited a comment on issue #1104: Please cut new Fauxton release (for CouchDB 2.2.0)

[GitBox]

popojargo edited a comment on issue #1104: Please cut new Fauxton release (for 
CouchDB 2.2.0)
URL: 
https://github.com/apache/couchdb-fauxton/issues/1104#issuecomment-405929166
 
 
   Hi @wohali , I faced a weird notification error while setuping a CouchDB 
cluster with the latest version of Fauxton. This error is probably due to my 
recent refactor of the setup addon(#943 ). I would like to review this tomorrow 
before any cut. 
   


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

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
 
 Review comment:
   I helped @garbados a bit with this PR before it landed here. The issue is 
that the `_dbs` documents get huge with `n=6`. `n=2` was selected solely to 
keep the example manageable without ellipses in the documentation.
   
   Would a disclaimer that `n=2` was selected solely for example purposes and 
is **not** recommended in production be acceptable here? We can then state the 
recommended values are `n=1` for single-node deployments, and `n=3` for 
clusters of 3 nodes or larger (with 2-node clusters strongly recommended 
against).


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

[GitHub] popojargo commented on issue #1104: Please cut new Fauxton release (for CouchDB 2.2.0)

[GitBox]

popojargo commented on issue #1104: Please cut new Fauxton release (for CouchDB 
2.2.0)
URL: 
https://github.com/apache/couchdb-fauxton/issues/1104#issuecomment-405929166
 
 
   Hi @wohali , I faced a weird notification error while setuping a CouchDB 
cluster with 2.1.2 This error is probably due to my recent refactor of the 
setup addon(#943 ). I would like to review this tomorrow before any cut. 
   


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

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
 
 Review comment:
   My point being - if the explanation is use

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
 
 Review comment:
   Our documentation should be as self-contai

[GitHub] wohali commented on issue #1432: Support callback module data provider

[GitBox]

wohali commented on issue #1432: Support callback module data provider
URL: https://github.com/apache/couchdb/pull/1432#issuecomment-405917827
 
 
   @iilyak is there a strong motivation to merge it for 2.2.0?


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

[GitHub] wohali commented on issue #1454: Documentation: no description for the `$text` operator

[GitBox]

wohali commented on issue #1454: Documentation: no description for the `$text` 
operator
URL: https://github.com/apache/couchdb/issues/1454#issuecomment-405917152
 
 
   @shimaore correct, this requires the clouseau/dreyfus addon from Cloudant. 
We are unable to ship this add-on due to licensing restrictions as part of 
CouchDB. However, the `$text` operator is supported by Mango if this add-on is 
installed.
   
   I will reopen this against our documentation repository. A pull request to 
remove the references would be welcome!


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

[GitHub] wohali closed issue #1454: Documentation: no description for the `$text` operator

[GitBox]

wohali closed issue #1454: Documentation: no description for the `$text` 
operator
URL: https://github.com/apache/couchdb/issues/1454
 
 
   


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

[GitHub] glynnbird opened a new issue #103: Remove support for GeoCouch

[GitBox]

glynnbird opened a new issue #103: Remove support for GeoCouch
URL: https://github.com/apache/couchdb-nano/issues/103
 
 
   This library has `spatial` function that models CouchDB + GeoCouch, a 
configuration that doesn't exist in the CouchDB 2.0 world. Perhaps this option 
should be removed?
   
   ## Actions needed
   
   Remove the `spatial` function and `viewSpatial` helper function.
   
   
   


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203361835
 
 

 ##
 File path: lib/nano.js
 ##
 @@ -612,6 +688,12 @@ module.exports = exports = nano = function dbScope(cfg) {
   return view(ddoc, viewName, {type: 'view'}, qs, callback);
 }
 
+// 
http://docs.couchdb.org/en/latest/api/ddoc/views.html#post--db-_design-ddoc-_view-view
+function viewDocsAsStream(ddoc, viewName, qs, callback) {
+  return view(ddoc, viewName, {type: 'view', stream: true}, qs, callback);
+}
+
+
 // geocouch
 function viewSpatial(ddoc, viewName, qs, callback) {
 
 Review comment:
   I'll create an issue to track 
this.https://github.com/apache/couchdb-nano/issues/103


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203361001
 
 

 ##
 File path: lib/nano.js
 ##
 @@ -471,12 +514,27 @@ module.exports = exports = nano = function dbScope(cfg) {
 
 // 
http://docs.couchdb.org/en/latest/api/document/common.html#head--db-docid
 function headDoc(docName, callback) {
-  return relax({
-db: dbName,
-doc: docName,
-method: 'HEAD',
-qs: {}
-  }, callback);
+  // this function doesn't pass on the Promise from relax because it needs
+  // to return the headers when resolving the Promise
+  return new Promise(function(resolve, reject) {
+relax({
+  db: dbName,
+  doc: docName,
+  method: 'HEAD',
+  qs: {}
+}, function(err, body, headers) {
+  if (err) {
+if (callback) {
+  callback(err);
 
 Review comment:
   Good point 👍 


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203359147
 
 

 ##
 File path: lib/nano.js
 ##
 @@ -190,67 +269,13 @@ module.exports = exports = nano = function dbScope(cfg) {
 
 log(req);
 
-if (!callback) {
-  return httpAgent(req);
+if (opts.stream) {
+  return httpAgent(req, responseHandler(req, opts, null, null, callback));
 
 Review comment:
   👍 
   


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203358933
 
 

 ##
 File path: lib/nano.js
 ##
 @@ -68,6 +67,89 @@ module.exports = exports = nano = function dbScope(cfg) {
 }
 return str;
   }
+  var responseHandler = function(req, opts, resolve, reject, callback) {
+
+return function(e, h, b) {
+  var parsed;
+  var rh = h && h.headers || {};
+  rh.statusCode = h && h.statusCode || 500;
+  rh.uri = req.uri;
+  if (e) {
+log({err: 'socket', body: b, headers: rh});
+var ret_e = errs.merge(e, {
+  message: 'error happened in your connection',
+  scope: 'socket',
+  errid: 'request'
+});
+if (reject) {
+  reject(ret_e);
+} 
+if (callback) {
+  callback(ret_e);
+}
+return ;
+  }
+
+  delete rh.server;
+  delete rh['content-length'];
+
+  if (opts.dontParse) {
+parsed = b;
 
 Review comment:
   👍 


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203358114
 
 

 ##
 File path: lib/nano.js
 ##
 @@ -68,6 +67,89 @@ module.exports = exports = nano = function dbScope(cfg) {
 }
 return str;
   }
+  var responseHandler = function(req, opts, resolve, reject, callback) {
+
+return function(e, h, b) {
+  var parsed;
+  var rh = h && h.headers || {};
+  rh.statusCode = h && h.statusCode || 500;
+  rh.uri = req.uri;
+  if (e) {
+log({err: 'socket', body: b, headers: rh});
+var ret_e = errs.merge(e, {
 
 Review comment:
   👍 


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203356847
 
 

 ##
 File path: lib/nano.js
 ##
 @@ -68,6 +67,89 @@ module.exports = exports = nano = function dbScope(cfg) {
 }
 return str;
   }
+  var responseHandler = function(req, opts, resolve, reject, callback) {
+
+return function(e, h, b) {
 
 Review comment:
   👍 `h` is actually the response!! `h` is from the original code. I'm 
refactoring with sensible names!


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

[GitHub] glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98

[GitBox]

glynnbird commented on a change in pull request #102: Promise support for Nano 
- Issue 98
URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r203356360
 
 

 ##
 File path: lib/nano.js
 ##
 @@ -68,6 +67,89 @@ module.exports = exports = nano = function dbScope(cfg) {
 }
 return str;
   }
+  var responseHandler = function(req, opts, resolve, reject, callback) {
+
+return function(e, h, b) {
+  var parsed;
+  var rh = h && h.headers || {};
 
 Review comment:
   👍 This e/h/b business is historic. I've refactored this function to aid 
readability.


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

[GitHub] AlexanderKaraberov edited a comment on issue #1195: Add support for bulk get with Accept:"multipart/mixed" or "multipart/related"

[GitBox]

AlexanderKaraberov edited a comment on issue #1195: Add support for bulk get 
with Accept:"multipart/mixed" or "multipart/related"
URL: https://github.com/apache/couchdb/pull/1195#issuecomment-405902159
 
 
   Hi,
   is there a small chance this PR might be reviewed before the 2.2.0 release? 
It would be nice to have this functionality in the CouchDB 2.2


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

[GitHub] iilyak commented on issue #1432: Support callback module data provider

[GitBox]

iilyak commented on issue #1432: Support callback module data provider
URL: https://github.com/apache/couchdb/pull/1432#issuecomment-405902416
 
 
   @tonysun83: I am not sure if we can merge this PR before CouchDB release. 


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

[GitHub] AlexanderKaraberov commented on issue #1195: Add support for bulk get with Accept:"multipart/mixed" or "multipart/related"

[GitBox]

AlexanderKaraberov commented on issue #1195: Add support for bulk get with 
Accept:"multipart/mixed" or "multipart/related"
URL: https://github.com/apache/couchdb/pull/1195#issuecomment-405902159
 
 
   Hi,
   is there a small chance this PR might be reviewed before the 2.2.0 release? 
It would nice to have this functionality in the CouchDB 2.2


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

[GitHub] iilyak commented on a change in pull request #1432: Support callback module data provider

[GitBox]

iilyak commented on a change in pull request #1432: Support callback module 
data provider
URL: https://github.com/apache/couchdb/pull/1432#discussion_r203345793
 
 

 ##
 File path: src/couch_epi/src/couch_epi_data.erl
 ##
 @@ -102,12 +102,15 @@ definitions({file, FilePath}) ->
 {error, Reason} ->
 {error, {FilePath, Reason}}
 end;
-definitions({module, Module}) when is_atom(Module) ->
-definitions({module, [Module]});
-definitions({module, Modules}) ->
+definitions({static_module, Module}) when is_atom(Module) ->
+definitions({static_module, [Module]});
+definitions({static_module, Modules}) ->
 Data = lists:append([M:data() || M <- Modules]),
 Hash = couch_epi_functions_gen:hash(Modules),
-{ok, Hash, Data}.
+{ok, Hash, Data};
+definitions({callback_module, Module}) ->
+Data = Module:data(),
 
 Review comment:
   @tonysun83: Are you OK if we keeping both providers?
- `static_module`
   - `callback_module`


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

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+---

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+---

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+---

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
 Review comment:
   Is it worth noting that `n=3` is a generally accepted value for high data 
resilience to node loss? Unfortunately I don't have a link to something 
explaining why :(


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

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+---

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+---

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+---

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
+---

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

[GitBox]

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

 ##
 File path: src/cluster/sharding.rst
 ##
 @@ -12,290 +12,490 @@
 
 .. _cluster/sharding:
 
-
-Sharding
-
+
+Shard Management
+
 
 .. _cluster/sharding/scaling-out:
 
-Scaling out
-===
+Introduction
+
 
-Normally you start small and grow over time. In the beginning you might do just
-fine with one node, but as your data and number of clients grows, you need to
-scale out.
+A `shard
+`__ is a
+horizontal partition of data in a database. Partitioning data into
+shards and distributing copies of each shard (called "shard replicas" or
+just "replicas") to different nodes in a cluster gives the data greater
+durability against node loss. CouchDB clusters automatically shard
+databases and distribute the subsections of documents that compose each
+shard among nodes. Modifying cluster membership and sharding behavior
+must be done manually.
 
-For simplicity we will start fresh and small.
+Shards and Replicas
+~~~
 
-Start ``node1`` and add a database to it. To keep it simple we will have 2
-shards and no replicas.
+How many shards and replicas each database has can be set at the global
+level, or on a per-database basis. The relevant parameters are *q* and
+*n*.
 
-.. code-block:: bash
+*q* is the number of database shards to maintain. *n* is the number of
+copies of each document to distribute. The default value for n is 3,
+and for q is 8. With q=8, the database is split into 8 shards. With
+n=3, the cluster distributes three replicas of each shard. Altogether,
+that's 24 shards for a single database. In a default 3-node cluster,
+each node would receive 8 shards. In a 4-node cluster, each node would
+receive 6 shards. We recommend in the general case that the number of
+nodes in your cluster should be a multiple of n, so that shards are
+distributed evenly.
 
-curl -X PUT "http://xxx.xxx.xxx.xxx:5984/small?n=1&q=2"; --user daboss
+CouchDB nodes have a ``etc/default.ini`` file with a section named
+``[cluster]`` which looks like this:
 
-If you look in the directory ``data/shards`` you will find the 2 shards.
+::
 
-.. code-block:: text
+[cluster]
+q=8
+n=3
 
-data/
-+-- shards/
-|   +-- -7fff/
-|   |-- small.1425202577.couch
-|   +-- 8000-/
-|-- small.1425202577.couch
+These settings can be modified to set sharding defaults for all
+databases, or they can be set on a per-database basis by specifying the
+``q`` and ``n`` query parameters when the database is created. For
+example:
 
-Now, check the node-local ``_dbs_`` database. Here, the metadata for each
-database is stored. As the database is called ``small``, there is a document
-called ``small`` there. Let us look in it. Yes, you can get it with curl too:
+.. code:: bash
 
-.. code-block:: javascript
+$ curl -X PUT "$COUCH_URL/database-name?q=4&n=2"
 
-curl -X GET "http://xxx.xxx.xxx.xxx:5986/_dbs/small";
+That creates a database that is split into 4 shards and 2 replicas,
+yielding 8 shards distributed throughout the cluster.
 
+Quorum
+~~
+
+Depending on the size of the cluster, the number of shards per database,
+and the number of shard replicas, not every node may have access to
+every shard, but every node knows where all the replicas of each shard
+can be found through CouchDB's internal shard map.
+
+Each request that comes in to a CouchDB cluster is handled by any one
+random coordinating node. This coordinating node proxies the request to
+the other nodes that have the relevant data, which may or may not
+include itself. The coordinating node sends a response to the client
+once a `quorum
+`__ of
+database nodes have responded; 2, by default.
+
+The size of the required quorum can be configured at
+request time by setting the ``r`` parameter for document and view
+reads, and the ``w`` parameter for document writes. For example, here
+is a request that specifies that at least two nodes must respond in
+order to establish a quorum:
+
+.. code:: bash
+
+$ curl "$COUCH_URL:5984/?r=2"
+
+Here is a similar example for writing a document:
+
+.. code:: bash
+
+$ curl -X PUT "$COUCH_URL:5984/?w=2" -d '{...}'
+
+Setting ``r`` or ``w`` to be equal to ``n`` (the number of replicas)
+means you will only receive a response once all nodes with relevant
+shards have responded or timed out, and as such this approach does not
+guarantee `ACIDic consistency
+`__. Setting ``r`` or
+``w`` to 1 means you will receive a response after only one relevant
+node has responded.
+
+.. _cluster/sharding/move:
+
+Moving a shard
 
 Review co