Postgres cluster concepts in plain words

The handful of ideas you need to understand CoyoteDB, a multi-node PostgreSQL cluster: nodes, the main node, voting, the witness and invite codes.

CoyoteDB is real PostgreSQL 18 wrapped in one small app called coyote. You install coyote, and it downloads and runs Postgres for you. Run it on more than one computer and those computers keep your data in sync.

Node

A node is one computer running coyote. Each data node holds a full copy of your database.

Cluster

A cluster is all your nodes together. To your app, the cluster looks like one Postgres database.

Main node

At any moment, one node is the main node. It takes the writes. The other nodes keep live copies, ready to take over.

Saved means saved twice

In normal running, a write only counts as saved once a second data node has it. So if one computer dies right after you save, the data is still on another one.

If only one data node is left, saves pause for about 30 seconds, then carry on using that one node. Until the other node is back and caught up there is no second copy, and CoyoteDB shows a clear warning. An optional stricter setting makes saves wait instead. (A 1-node setup never has a second copy.)

Voting

The nodes vote on which one is the main node. A node needs more than half the votes. With three nodes, two votes win.

Witness

A witness is a tiny helper that holds no data. It only votes. Adding a witness to two data nodes gives them a tie-breaker, so they can switch over automatically.

No split brain

If a node gets cut off from the others, it shuts its database down before another node takes over. So two nodes never both think they are in charge. People call that problem “split brain”; CoyoteDB is built to avoid it.

Connect to any node

Every node is built to listen on the normal Postgres port and pass you to the current main node, so you can point your app at any node. This part is not available yet; for now, your app connects with the connection string a node prints (coyote conninfo). Any Postgres tool or library works.

Invite codes

You set up a cluster with invite codes. Start the first node, ask it for a code, and paste that code on the next computer.

Networks

Nodes talk to each other over one encrypted port. That works over Tailscale, Twingate, UniFi or another site-to-site VPN, or a plain local network.