Skip to content

High availability for SQLite

Run the same app on several servers, and when the one that writes goes down, another takes over with every change it received.

One origin, any number of replicas

Every server runs the same code, and your Litebackup server decides which one writes.

  1. Identical servers

    Each runs your app and Litebackup with the same database path.

  2. One origin

    One server becomes the origin: it takes writes and backs up every change.

  3. Live replicas

    The others keep a readonly copy current within seconds.

  4. Automatic takeover

    When the origin goes quiet, a replica becomes the origin.

A takeover you can trust

The new origin starts from every change your Litebackup server received.

  • One writer at a time

    Your Litebackup server lets only one server write at a time.

  • No gap for writes

    The new origin takes writes on the same file the moment it is promoted.

  • Nothing deleted

    Writes a returning old origin never sent are kept as a copy and reported.

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.