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.
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.
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.
| Setup | Nodes | Copies of your data | If the main node stops |
|---|---|---|---|
| 1 computer | 1, no backup | None. Down until it is backNothing to vote on | |
| 2 computers | 2 | Copy safe; down until it is backTwo nodes cannot out-vote each other | |
| 2 computers + witness | 2 | AutomaticThe witness breaks the tie | |
| 3 or more computers | 3 or more | AutomaticAny 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
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.
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.
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