You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by wo...@apache.org on 2019/01/15 17:31:59 UTC
[couchdb-documentation] 01/01: Improve placement docs, closes #374
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