How it works

How CoyoteDB keeps your data up, in plain words.

Inside every node is real PostgreSQL 18. The CoyoteDB app around it keeps the nodes in sync and decides who is in charge. Here is how, one idea at a time.

A few words first

Node
One computer running the CoyoteDB app.
Cluster
All your nodes together. To your app, it is one database.
Main node
The node that takes writes right now. The others keep live copies.
Witness
A tiny helper with no data. It only votes, to break ties.

1 · Sync

A save counts once two computers have it.

When a second data node is up, which is always the case in normal running, CoyoteDB waits until it has a copy before it says "saved". So losing one computer does not lose that write.

When only one data node is left: Saves pause for about 30 seconds, then carry on using the one node that is left. Until the other node is back and caught up, there is no second copy, and CoyoteDB shows a clear warning. If you would rather have saves wait than run on one copy, an optional stricter setting makes them wait until a second node is back.

A 1-node setup works, but has no backup: there is no second place for the data to live.

In normal running: your app writes to the main node. The main node sends the write to a second node. When the second node has it, your app hears "saved".Your appmaincopy1 write2 copy3 got it4 savedon two nodes before "saved"

2 · Voting

The nodes vote on who is in charge.

One node is the main node. It takes the writes. The nodes agree on which one that is by voting, so there is never any doubt.

A node needs more than half the votes to be in charge. With three nodes, two votes win. That is why two nodes alone cannot switch over by themselves: if they lose touch, neither has a majority. A witness, or a third node, fixes that.

Three nodes. Two of them vote for node A. With two of three votes, node A is the main node.ABCB: A ✓C: A ✓2 of 3 → A is main

At a glance

How many computers, and what you get.

More nodes means more copies and, from three (or two and a witness), switch-over without you. Node counts explained has the details.

What each node count gives you
SetupNodesCopies of your dataIf the main node stops
1 computer1, no backupNone. Down until it is backNothing to vote on
2 computers2Copy safe; down until it is backTwo nodes cannot out-vote each other
2 computers + witness2AutomaticThe witness breaks the tie
3 or more computers3 or moreAutomaticAny two of three are a majority

3 · Cut-off safety

A cut-off node steps aside on its own.

If a node loses touch with the others, it shuts its database down before another node takes over. Two nodes never both think they are in charge (people call that "split brain").

Picture a network cable getting pulled. The old main node is now alone. It cannot get a majority, so it turns its database off. Only then do the other nodes pick a new main node. Your data never splits into two versions.

How long it takes: a new main node is in place about 10 seconds after a hard kill (6 to 11 seconds), and writes flow again in roughly 10 to 25 seconds (measured on one Mac, default settings). Checked on macOS with 26 integration tests with real Postgres, and a chaos suite of 27 fault scenarios plus randomized runs (kill, freeze, cut-off), where a checker confirmed no acknowledged write was lost and there were never two main nodes at once. How we test it, including power cuts

The network between node A and the others is cut. Node A is alone, so it turns its database off. Nodes B and C still have a majority and B becomes the new main node.Aalone: database offBnew mainC2 of 3

4 · Connect to any node Not available yet

Connect to any node.

Every node listens on the normal Postgres port and passes you along to the current main node. Any Postgres tool or library works. This part is not available yet.

CoyoteDB speaks standard Postgres. If a tool can talk to Postgres, it can talk to CoyoteDB. You do not need a special driver.

Your app connects to node C, which is a copy. Node C passes the connection on to node A, the current main node.Your appABCconnectpassed to main

5 · Mixing systems

Today, data computers share one system type.

Today, the computers that hold data in one cluster must share one system type: all Windows, all Linux, or all Mac with the same chip family. Support for mixing Windows, Linux and Mac data computers is being built and tested now. Until it has been proven safe, CoyoteDB refuses a mixed join rather than risk your data. The witness and the apps that connect can already run on any system.

So for now, pick one system type for the computers that hold your data. Your laptop can still connect to them, whatever it runs.

Works today: three data nodes that are all Linux, with a witness on any system. Coming: data nodes that mix Windows, Mac and Linux in one cluster, which CoyoteDB refuses until it is proven safe.✓ WorksLinuxLinuxLinuxwitnessany systemdata nodes: same typeComing: mixedWindowsMacLinuxmixed data nodes: refused for now

Ready to see which setup fits you?

Nodes talk to each other over one encrypted port. Pick your system, your number of computers and your network.

Open the setup guide