What you set up
Run two or more identical servers, such as three VMs or containers behind a load balancer. Each one runs your app and Litebackup, joined to the same Litebackup server with a join token, and each calls failover() on the same database path. There is nothing else to configure, and you can add or remove servers at any time.
import { failover } from "@litebackup/sdk";
const cluster = await failover("/var/lib/app/main.sqlite");
The SDK page has a complete Express app, and the same in Go.
How the origin is chosen
When the servers start, one of them becomes the origin. Its file is the database: your app writes to it as usual, and every change reaches your Litebackup server within seconds.
The others become replicas. Each keeps a live readonly copy at the same path, within seconds of the origin, and serves reads from it. Writes to a replica are refused, so a request that reaches the wrong server cannot change your data.
When the origin goes down
When the origin stops, one replica takes over, and writes resume about 60 seconds after the origin stopped. To change that, set --session-lease on your Litebackup server: a shorter time means a faster takeover, and a brief network outage is more likely to cause one.
The new origin starts from the last change your Litebackup server received, and your app can write the moment it is promoted. Changes from the last few seconds before the origin stopped may not have left it yet.
writer() returns the machine that writes and whether it is still active.
While your Litebackup server is unreachable, the origin keeps writing and no takeover happens.
When the old origin comes back
A returning old origin cannot write again: another server writes now. Any local writes it never sent are saved as a conflict copy, never deleted, and reported through the conflictSaved event and litebackup conflict list. Then it becomes a replica of the new origin.
Send writes to the origin
Every server can answer reads. Writes must reach the origin, so give your app a health check that answers 200 only there:
app.get("/healthz/origin", (req, res) => {
res.sendStatus(cluster.isOrigin ? 200 : 503);
});
Then point your load balancer's write traffic at the servers that pass it. With HAProxy, for example, reads go to every server and everything else goes to the origin:
frontend app
mode http
bind :80
use_backend writes if !METH_GET
default_backend reads
backend reads
mode http
server web-1 10.0.0.1:3000 check
server web-2 10.0.0.2:3000 check
server web-3 10.0.0.3:3000 check
backend writes
mode http
option httpchk GET /healthz/origin
server web-1 10.0.0.1:3000 check
server web-2 10.0.0.2:3000 check
server web-3 10.0.0.3:3000 check
cluster.on("origin") and cluster.on("replica") tell your app when its role changes. A replica is a few seconds behind, so read from the origin when a page must show a write it just made.
With the command line
The same works without changing your code. Run this on every server:
sudo litebackup failover /var/lib/app/main.sqlite
sudo litebackup writer main.sqlite # the machine that writes now
litebackup status shows each database's role on this machine. The command line page has every command.