Backup & Restore

Narratorr automatically backs up its database on a schedule. Backups capture the complete database (books, settings, history, everything) as a compressed zip file.

Automated Backups

Configure in Settings > System.

Setting	Description
Backup Interval	How often to create a backup, in minutes. Range: 60–43,200 (1 hour to 30 days). Default: 10,080 (weekly).
Backup Retention	Number of backups to keep. Older backups are automatically pruned. Range: 1–100. Default: 7.

Backups are stored in config/backups/ (in Docker, this is inside the /config volume).

What Gets Backed Up

Each backup is a zip file containing a consistent SQLite snapshot of your database. This includes:

• All books, authors, and series data
• Settings and configuration
• Download history and event history
• Blacklist entries
• Import list configuration
• Notification configuration
• User accounts

Library audio files are not included in backups — only the database. Back up your library volume separately.

Manual Backup

Trigger a backup manually with the Create Backup button under Settings > System > Backup & Restore. This creates an immediate backup regardless of the schedule.

Downloading Backups

From Settings > System > Backup & Restore, download any backup file to store off-site. This is recommended — if your config volume is lost, the backups stored inside it are lost too.

Restoring from Backup

Restore is a two-step process to prevent accidental data loss:

1. Upload — select a backup zip file. Narratorr extracts and validates it:
   • Checks it contains a valid SQLite database
   • Verifies the migration count is compatible (can’t restore a backup from a newer version)
   • Extraction is capped at 1 GB of uncompressed database to guard against malformed or zip-bomb uploads. A legitimately larger database needs the cap raised.
2. Confirm — review the validation results and confirm. The pending restore has a 5-minute window — if you don’t confirm in time, it expires and you need to re-upload.

After confirmation, Narratorr stages the restore file and the server process exits — it does not restart itself. Under a process supervisor (Docker, systemd) it comes back automatically; if you run Narratorr via pnpm start or node directly, you must restart it manually. On the next startup it swaps the staged database in and runs any pending migrations.

You can also restore directly from any backup shown in the Backups list using its Restore (history) icon — it runs the same validate-then-confirm flow as upload, without needing to re-upload the file. Reserve the Upload path for restoring an off-site or downloaded backup.

Caution

Restoring replaces your entire database. Everything added since the backup was created will be lost. Download a fresh backup before restoring if you want a safety net.

Pre-1.0 backups can’t be restored

Backups created before the 1.0 migration flatten will fail validation with a “newer version” error and cannot be restored into 1.0+. The migration history was reset to a single baseline, so a pre-flatten backup reports more migrations than the current app and is rejected even though it is actually older. This is expected one-time breakage — migrate off pre-flatten versions before relying on backups.