Backup and restore

Backup

node dist/cli.js backup ~/backups/bus-$(date +%F).db

• Safe while serve runs. It uses SQLite VACUUM INTO.
• The target file must not exist.
• The copy is a single file with a fresh bus_instance_id.

Restore

1. Stop the service:

   launchctl bootout gui/$(id -u)/com.catesworks.session-bus   # macOS
   systemctl --user stop session-bus                           # Linux

2. Restore:

   node dist/cli.js restore ~/backups/bus-2026-10-28.db

3. Start the service again (launchctl bootstrap ... or systemctl --user start session-bus).

restore exits 3 with bus.db locked by pid N; stop serve first while serve runs. There is no --force.

What restore does

It holds the database lock for the whole run, copies the backup to a temporary file, checks that it is a bus database, assigns a fresh bus_instance_id, fsyncs, removes the old -wal and -shm files so they cannot be replayed onto the restored data, renames the file into place and fsyncs the directory. If the backup is not a bus database, the live file is untouched.

Effect on sessions

• Mail and sessions are as they were at backup time. Anything sent after the backup is gone.
• Push shims see the new bus_instance_id, reset their cursor to 0 and push all unacked mail again. Expect repeats; delivery is at-least-once.