Skip to content

Data, backups and upgrades

One SQLite file holds all the state of an instance for its network. Part of it is evidence that nothing can regenerate, so handle the file with care.

What is in the database

  • The mirror of every hub's log: tiles and entry bundles. It is the bulk of the file. The monitor could fetch it again from the hubs.
  • Irreplaceable evidence: the checkpoints the monitor observed, the contradicting checkpoints of any frozen hub, and the OpenTimestamps proofs. If a hub goes offline or rewrites its log, nothing can recreate them.

Keep the file on a volume that outlives the container. A new container on the same file continues where the old one stopped.

Backups

The database runs in SQLite's WAL mode, so recent changes can sit in two files next to it. Back up all three files as one set: monitor.db, monitor.db-wal and monitor.db-shm. A copy of monitor.db alone, taken while the instance runs, can miss the latest changes.

The simplest consistent backup is a copy taken while the instance is stopped. For a running instance, use SQLite's own backup, for example:

sqlite3 /data/monitor.db ".backup '/backup/monitor-$(date -u +%Y%m%dT%H%M%SZ).db'"

The image has no shell and no sqlite3, so run the command from another container that mounts the same volume.

Upgrades

  1. Snapshot the database (all three files). Keep the snapshot until the new version has proven itself.
  2. Change the image tag to the new :vX.Y.Z and restart.
  3. Check GET /version and the start page.

On startup, the new version migrates the database automatically, one transaction per step. If a step fails, the database stays as it was and the monitor does not start.

Warning

Never recreate the volume to get a clean schema. That destroys the evidence.

Rollbacks

Between versions with the same database schema, a rollback is a tag change. A version refuses a database that a newer version migrated, so a rollback across a migration means restoring the snapshot from before the upgrade. You lose everything the monitor observed since then.

Rules

  • One running instance per database file. The monitor is the only writer of the file.
  • uid 65532, the user of the image, must be able to write to the volume. See Deploy.