2.4 KiB
06 - Backup
Scope
QuoteForge creates rotating local ZIP backups of:
- a consistent SQLite snapshot saved as
qfs.db; config.yamlwhen present.
The backup intentionally does not include local_encryption.key.
Location and naming
Default root:
<db dir>/backups
Subdirectories:
daily/weekly/monthly/yearly/
Archive name:
qfs-backp-YYYY-MM-DD.zip
Retention
| Period | Keep |
|---|---|
| Daily | 7 |
| Weekly | 4 |
| Monthly | 12 |
| Yearly | 10 |
Behavior
- on startup, QuoteForge creates a backup if the current period has none yet;
- a daily scheduler creates the next backup at
backup.time; - duplicate snapshots inside the same period are prevented by a period marker file;
- old archives are pruned automatically.
Safety rules
- backup root must be outside the git worktree;
- backup creation is blocked if the resolved backup root sits inside the repository;
- SQLite snapshot must be created from a consistent database copy, not by copying live WAL files directly;
- restore to another machine requires re-entering DB credentials unless the encryption key is migrated separately.
Restore
- stop QuoteForge;
- unpack the chosen archive outside the repository;
- replace
qfs.db; - replace
config.yamlif needed; - restart the app;
- re-enter MariaDB credentials if the original encryption key is unavailable.
Pre-reset safety backup
Before clearing any table, -reset-localdb creates a fresh ZIP under
<backup root>/pre-reset/qfs-pre-reset-v1-<UTC timestamp>-<unique>.zip, outside
normal retention and regardless of QFS_BACKUP_DISABLE. The archive contains
a consistent SQLite snapshot and the selected config when present. Every ZIP
entry is read back for CRC validation; the extracted database must pass SQLite
integrity_check. A backup or verification failure prevents the reset. The
backup directory must also resolve outside git after following symlinks.
Reset refuses queued changes and any project/configuration not marked synced,
including NULL/legacy states. A missing sync-status column also blocks reset.
Only -reset-localdb -force-reset-localdb bypasses this data check. Deletions run
in one transaction and preserve connection settings. Missing legacy tables are
skipped. Use the restore procedure above for the pre-reset archive; retain it
until the reset has been verified. The environment reset switch was removed to
prevent repeated destructive startup.