74 lines
2.4 KiB
Markdown
74 lines
2.4 KiB
Markdown
# 06 - Backup
|
|
|
|
## Scope
|
|
|
|
QuoteForge creates rotating local ZIP backups of:
|
|
- a consistent SQLite snapshot saved as `qfs.db`;
|
|
- `config.yaml` when 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
|
|
|
|
1. stop QuoteForge;
|
|
2. unpack the chosen archive outside the repository;
|
|
3. replace `qfs.db`;
|
|
4. replace `config.yaml` if needed;
|
|
5. restart the app;
|
|
6. 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.
|