Backup & restore

A complete Dispatch backup is small and portable: the database holds almost everything, plus the encryption key and the bootstrap config file. Get all three and you can restore to a fresh host - on the same platform or a different one.

What to back up

1. The database - all config, message history, API keys, routing rules, and the audit log.
   • Bundled SQLite (the default): the database is a single file, dispatch.db, in the data directory (/var/lib/dispatch on Linux, C:\ProgramData\Dispatch on Windows). Back it up either by stopping the service and copying dispatch.db (plus any dispatch.db-wal / dispatch.db-shm sidecars), or - without stopping - with SQLite’s online backup: sqlite3 dispatch.db ".backup 'backup.db'".
   • A server engine you brought (PostgreSQL / MariaDB-MySQL / SQL Server): use that engine’s dump tool, e.g. pg_dump DispatchLog > dispatchlog.sql (or pg_dump -Fc for a compressed archive), mysqldump DispatchLog > dispatchlog.sql, or a SQL Server BACKUP DATABASE. For production, consider the engine’s point-in-time recovery as well.
2. The encryption key file .dispatch-key. Without it, encrypted secrets cannot be decrypted after a restore - provider API keys, SMTP passwords, and the TLS certificate password. It is a portable file on every platform, so restoring it alongside the database is what lets you move to a different machine:
   • Linux/macOS - mode 600, in the key/app directory (or DISPATCH_KEY_DIR).
   • Windows - in the data dir (C:\ProgramData\Dispatch\.dispatch-key); the installer ACL-locks that folder to SYSTEM + Administrators. (Older builds used DPAPI, which was machine-bound; those values migrate to the portable key on the next save.)
3. appsettings.json - the database connection string and the dashboard TLS certificate path.

The spool directory holds only in-flight and captured mail; drain it before planned maintenance rather than relying on a backup of it.

Restore

1. Put the database back:
   • SQLite: copy dispatch.db (and any -wal / -shm sidecars) into the data directory.
   • Server engine: create an empty database and load the dump (psql DispatchLog < dispatchlog.sql, pg_restore for a custom-format archive, mysql < dispatchlog.sql, or a SQL Server RESTORE).
2. Put .dispatch-key and appsettings.json back in place.
3. Start the service - the schema auto-migrates if the build is newer.

Moving between engines instead of restoring the same one? Use Dispatch.Service migrate-database rather than a dump and load - it copies a complete database from any engine to any other and verifies row counts.

Before upgrades

Always take a database backup before upgrading production. See Upgrading for the upgrade flow, and Security for how secrets are encrypted at rest.