Clusters

One node works on its own. With three or more, DB Branch keeps working when one node is down. The state is kept by Raft on every node, so any node takes commands, and snapshots are replicated between nodes.

Voters

Writes wait for a majority of the voting nodes. An even number of voters tolerates no more failures than the next lower odd number, and a split into two equal halves leaves neither side with a majority. So DB Branch lets only an odd number of nodes vote, at most 5 (1, 3 or 5). Other nodes are non-voters: they receive the log and hold a full copy of the data, but do not count in elections or majorities.

Nodes are promoted and demoted automatically. A node that joins starts as a non-voter and is promoted when it has been healthy for a while. db-branch cluster status shows which nodes vote.

Form a cluster

On the first node, as root:

sudo db-branch cluster init
db-branch cluster token

On each new node, install the package, run db-branch init --pool <pool>, then:

sudo db-branch cluster join <first-node>:7070 --token <token>

Check the members and the leader:

db-branch cluster status

The table shows each node’s role (leader or follower), whether it votes, its state, free pool space, installed engines and version. A new token replaces the previous one.

What the cluster does

• A branch is placed on a node chosen by load, among nodes that hold the base snapshot. --node picks one yourself.
• runtime install always applies to the whole cluster.
• Connecting to any node’s proxy reaches every branch. See Connecting to a branch.
• If the leader is unavailable, writes to cluster state return 503 no_leader. Connections to existing branches keep working.
• branch recreate builds a branch again on another node after its node is lost.

Nodes talk on port 7070 (node API, mutual TLS) and 7071 (Raft). The web console and external API use 7080.