3.3. Configuring Clustering

3.3.1. Cluster Options

[cluster]

  • q

Sets the default number of shards for newly created databases. The default value, 2, splits a database into 2 separate partitions.

  1. [cluster]
  2. q = 2

For systems with only a few, heavily accessed, large databases, or for servers with many CPU cores, consider increasing this value to 4 or 8.

The value of q can also be overridden on a per-DB basis, at DB creation time.

See also

PUT /{db}

  • n

Sets the number of replicas of each document in a cluster. CouchDB will only place one replica per node in a cluster. When set up through the Cluster Setup Wizard, a standalone single node will have n = 1, a two node cluster will have n = 2, and any larger cluster will have n = 3. It is recommended not to set n greater than 3.

  1. [cluster]
  2. n = 3
  • 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 the nodes database and # is an integer indicating the number of replicas to place on nodes with a matching zone_name.

This parameter is not specified by default.

  1. [cluster]
  2. placement = metro-dc-a:2,metro-dc-b:1

See also

Placing a database on specific nodes

  • seedlist

An optional, comma-delimited list of node names that this node should contact in order to join a cluster. If a seedlist is configured the _up endpoint will return a 404 until the node has successfully contacted at least one of the members of the seedlist and replicated an up-to-date copy of the _nodes, _dbs, and _users system databases.

[cluster] seedlist = couchdb@node1.example.com,couchdb@node2.example.com

3.3.2. RPC Performance Tuning

[rexi]

CouchDB uses distributed Erlang to communicate between nodes in a cluster. The rexi library provides an optimized RPC mechanism over this communication channel. There are a few configuration knobs for this system, although in general the defaults work well.

  • buffer_count

The local RPC server will buffer messages if a remote node goes unavailable. This flag determines how many messages will be buffered before the local server starts dropping messages. Default value is 2000.

  • server_per_node

By default, rexi will spawn one local gen_server process for each node in the cluster. Disabling this flag will cause CouchDB to use a single process for all RPC communication, which is not recommended in high throughput deployments.

  • stream_limit

    New in version 3.0.

This flag comes into play during streaming operations like views and change feeds. It controls how many messages a remote worker process can send to a coordinator without waiting for an acknowledgement from the coordinator process. If this value is too large the coordinator can become overwhelmed by messages from the worker processes and actually deliver lower overall throughput to the client. In CouchDB 2.x this value was hard-coded to 10. In the 3.x series it is configurable and defaults to 5. Databases with a high q value are especially sensitive to this setting.