What a cluster is here

A cluster here is a set of nodes that learn about each other through the same log they replicate data with. There is no coordinator process, no configuration file to keep in step, and no service to stand up beside the database. What a node knows about its peers is a catalog record, which means it arrives the way every other record arrives.

That single decision is what the rest of this section is about, and it is worth saying what it costs before saying what it gives.

What a cluster gives you

Each of these is a statement you run, and each is explained on its own page.

• Every acknowledged write survives a lost node. A write on a namespace kept on more than one node is acknowledged once a majority of its voters hold it, so the node elected next always has it (When a write is acknowledged).
• A lost leader is replaced without anyone being paged. Leadership is a lease a majority grants; a leader cut off from the others stops writing on its own before anyone else may start (Leadership and failover).
• Writes are taken by more than one machine. A table splits into shards and each shard — or a namespace, or a database — can be led by its own node (Splitting a table into shards, Who leads what).
• A transaction may still change records on two leaders at once, whole or not at all, when it asks to (Transactions across leaders).
• The cluster keeps itself in shape when told to. Shards split and merge within bounds you state, the store's leader evens out who leads what, a preferred node is handed its range back, and a placement can be given back to the store line (Who leads what).
• Any node answers. A read goes to a node that may answer it, a write sent to the wrong node is redirected or carried, and a node that holds part of a table gathers the rest (Reads, routing and staleness).
• It upgrades one node at a time, taking writes throughout (Upgrading a cluster).

Lines: the one picture to keep

Everything a cluster does is easier to follow with one idea in hand. The store is cut into ranges — the whole store, or a namespace, a database or a shard somebody placed — and each range is written as its own line: its own log, its own numbered leaderships, its own lease. One node leads a line and takes its writes; every other node that holds the range keeps a copy, collected from that leader, and votes on who leads next.

A cluster nobody has placed anything on has one line, the store line, and its leader writes everything. Placing a range with LEADS carves that range out into a line of its own, which is how two nodes come to take writes at once. The rest of this section is what happens on a line: who may lead it, when a write on it counts, what happens when its leader is lost, and how the lines are moved.

What being in a cluster changes

A store is on its own until its catalog names somebody else. One node with no peer declared behaves exactly as it always has: it writes, it is never fenced, it takes no lease. Nothing about a single-node deployment changes because this section exists.

From the moment the first peer that names another node is declared, three things become true at once:

• the node writes under a leadership, and until a majority grants it one it refuses every local write;
• what it may write is the ranges it leads, not every range it can reach;
• a write it may not take is sent where it can be taken — a client that can follow a redirect is given one, and a caller that cannot is carried over the peer link to that node (Reads, routing and staleness).

The consequence is worth stating plainly rather than discovering: a cluster that has elected nobody takes no writes anywhere. That is a real availability change from a set of nodes that each accepted writes the others would never see — and it is the point. The second arrangement is faster and quietly wrong.

Where each question is answered

The vocabulary, once

Four words carry most of the weight, and three of them are easy to read as synonyms of each other.

A node is one running process with one store directory. It has an identifier, which INFO FOR NODE prints, and peers prove themselves to each other against it.

A peer is a node this one has been told about — a DEFINE REPLICA row in the catalog. A follower is a peer that has actually collected something. The gap between the two lists is the most useful thing either of them says: a peer that appears in the first and not the second has never asked this node for anything, and nothing else on the node will tell you that.

A range is what a leadership covers. On a cluster that elected a single leader it is the whole store, and the distinction never comes up. It starts mattering the moment two nodes lead two namespaces, at which point may this node write and may this node write here stop having one answer.

An epoch is a leadership, numbered. It is not a version, a timestamp or a block height: it is which run of which node wrote a record, and it exists so that two nodes that both believed they were leading can be told apart afterwards instead of having their histories silently merged.

What to look at when something is wrong

Three readings, each owned by the page that explains it. None of them needs a connection to the node you are asking about.

• INFO FOR NODE — what this machine is, who its peers are, which of them have actually collected, the epoch it leads under and the time left on its lease. It is the first thing to run against a node you have just been handed.
• cluster.lease at or near zero on a node that is still writing is the split-brain window, and it is the only shape in which that window is visible at all. See Leadership and failover.
• A follower's quiet_for and copy_age answer different questions and come apart on an idle node. See Reads, routing and staleness.

What this is not

A transaction across ranges is atomic, not globally ordered. A reader sees a transaction across leaders whole or not at all, but two readers on two ranges are not ordered against each other: there is no clock shared by the whole cluster, and write skew is admitted as it is under the store's snapshot isolation (Transactions across leaders). Records do not move between nodes on their own: a node holds what its subscription names, and a shard split or merged keeps its records where they were — what the cluster changes by itself is which shards exist and which node leads them, and only where you asked it to. A node holding part of a table answers a read of the rest from those shards' leaders, which filter, rank and fold their own shards so that only what the answer needs travels — a join or a FETCH into a shard it lacks is gathered the same way. And every setting on every page is a statement you run against a node, which is what makes all of it scriptable and all of it reviewable — the web console builds a cluster by composing these same statements, and shows each one before it is sent.