[couchdb-documentation] branch 374-clarify-placement created (now 4253a0d)

[wo...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wohali pushed a change to branch 374-clarify-placement
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git.


      at 4253a0d  Improve placement docs, closes #374

This branch includes the following new commits:

     new 4253a0d  Improve placement docs, closes #374

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[couchdb-documentation] 01/01: Improve placement docs, closes #374

[wo...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wohali pushed a commit to branch 374-clarify-placement
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit 4253a0de81ac7dd6b0a1b26425162992bacfdc9e
Author: Joan Touzet <jo...@atypical.net>
AuthorDate: Tue Jan 15 12:31:40 2019 -0500

    Improve placement docs, closes #374
---
 src/cluster/databases.rst | 5 +++++
 src/cluster/sharding.rst  | 8 ++++++++
 src/config/cluster.rst    | 5 +++++
 3 files changed, 18 insertions(+)

diff --git a/src/cluster/databases.rst b/src/cluster/databases.rst
index f008eb6..09876d0 100644
--- a/src/cluster/databases.rst
+++ b/src/cluster/databases.rst
@@ -51,6 +51,11 @@ In BigCouch, the predecessor to CouchDB 2.0's clustering functionality, there
 was the concept of zones. CouchDB 2.0 carries this forward with cluster
 placement rules.
 
+.. warning::
+
+    Use of the ``placement`` argument will **override** the standard
+    logic for shard replica cardinality (specified by ``[cluster] n``.)
+
 First, each node must be labeled with a zone attribute. This defines which
 zone each node is in. You do this by editing the node's document in the
 ``/nodes`` database, which is accessed through the "back-door" (5986) port.
diff --git a/src/cluster/sharding.rst b/src/cluster/sharding.rst
index aeb8d02..cc7268e 100644
--- a/src/cluster/sharding.rst
+++ b/src/cluster/sharding.rst
@@ -468,6 +468,11 @@ Specifying database placement
 You can configure CouchDB to put shard replicas on certain nodes at
 database creation time using placement rules.
 
+.. warning::
+
+    Use of the ``placement`` option will **override** the ``n`` option,
+    both in the ``.ini`` file as well as when specified in a ``URL``.
+
 First, each node must be labeled with a zone attribute. This defines
 which zone each node is in. You do this by editing the node’s document
 in the ``/_nodes`` database, which is accessed through the node-local
@@ -509,6 +514,9 @@ when the database is created, using the same syntax as the ini file:
 
     curl -X PUT $COUCH_URL:5984/<dbname>?zone=<zone>
 
+The ``placement`` argument may also be specified. Note that this *will*
+override the logic that determines the number of created replicas!
+
 Note that you can also use this system to ensure certain nodes in the
 cluster do not host any replicas for newly created databases, by giving
 them a zone attribute that does not appear in the ``[cluster]``
diff --git a/src/config/cluster.rst b/src/config/cluster.rst
index 969f7e2..a7d605f 100644
--- a/src/config/cluster.rst
+++ b/src/config/cluster.rst
@@ -56,6 +56,11 @@ Cluster Options
 
     .. config:option:: placement
 
+    .. warning::
+
+        Use of this option will **override** the ``n`` option for replica
+        cardinality. Use with care.
+
     Sets the cluster-wide replica placement policy when creating new
     databases. The value must be a comma-delimited list of strings of the
     format ``zone_name:#``, where ``zone_name`` is a zone as specified in