4.1. Theory — Apache CouchDB® 3.5 Documentation

# 4.1. Theory

Before we move on, we need some theory.

As you see in `etc/default.ini` there is a section called `[cluster]`

    [cluster]
    q=2
    n=3

- `q` - The number of shards.

- `n` - The number of copies there is of every document. Replicas.

When creating a database you can send your own values with request and thereby override the defaults in `default.ini`.

The number of copies of a document with the same revision that have to be read before CouchDB returns with a `200` is equal to a half of total copies of the document plus one. It is the same for the number of nodes that need to save a document before a write is returned with `201`. If there are less nodes than that number, then `202` is returned. Both read and write numbers can be specified with a request as `r` and `w` parameters accordingly.

We will focus on the shards and replicas for now.

A shard is a part of a database. It can be replicated multiple times. The more copies of a shard, the more you can scale out. If you have 4 replicas, that means that all 4 copies of this specific shard will live on at most 4 nodes. No node can have more than one copy of each shard replica. The default for CouchDB since 3.0.0 is `q=2` and `n=3`, meaning each database (and secondary index) is split into 2 shards, with 3 replicas per shard, for a total of 6 shard replica files. For a CouchDB cluster only hosting a single database with these default values, a maximum of 6 nodes can be used to scale horizontally.

Replicas add failure resistance, as some nodes can be offline without everything crashing down.

- `n=1` All nodes must be up.

- `n=2` Any 1 node can be down.

- `n=3` Any 2 nodes can be down.

- etc

Computers go down and sysadmins pull out network cables in a furious rage from time to time, so using `n<2` is asking for downtime. Having too high a value of `n` adds servers and complexity without any real benefit. The sweet spot is at `n=3`.

Say that we have a database with 3 replicas and 4 shards. That would give us a maximum of 12 nodes: 4*3=12.

We can lose any 2 nodes and still read and write all documents.

What happens if we lose more nodes? It depends on how lucky we are. As long as there is at least one copy of every shard online, we can read and write all documents.

So, if we are very lucky then we can lose 8 nodes at maximum.