8000 V0-16: Add rotating backup, restore, and migration safety by kiran-brahma · Pull Request #36 · kiran-brahma/nodepad-app · GitHub
[go: up one dir, main page]

Skip to content

V0-16: Add rotating backup, restore, and migration safety - #36

Merged
kiran-brahma merged 2 commits into
mainfrom
claude/issue-17-backup-restore
Jul 23, 2026
Merged

kiran-brahma merged 2 commits into
mainfrom
claude/issue-17-backup-restore

Conversation

@kiran-brahma
@kiran-brahma kiran-brahma commented Jul 23, 2026 •
Copy link
Copy Markdown
Owner

Closes #17.

What this adds

Local rotating backup, restore, and migration safety for the durable SQLite database. Backups live in the macOS application-data folder under a backups subdirectory, are produced with SQLite-safe VACUUM INTO semantics (never a naive copy of a live WAL database), and carry a JSON manifest sidecar with schema version, created time, app version, sha256 checksum, and backup kind.

  • src-tauri/src/backup.rs — a new deep module owning backup creation, validation (checksum + PRAGMA integrity_check + supported schema), retention (seven automatic; four each pre-migration/pre-restore), a full-scan data fingerprint, and atomic file replacement that preserves the current database on any failure. Connection-agnostic.
  • WorkspaceStore::open_with_backup — guards every pending migration with a verified pre-migration backup, or aborts without migrating. The migrations list is extracted so the pending-count check and the migrator share one source.
  • WorkspaceStore::maybe_automatic_backup — at most once per calendar day, only after durable data changed since the last backup. Tracking state lives in a backup-state.json sidecar so recording it never changes the fingerprint it compares against.
  • restore_backup command — re-validates the selected backup, makes a pre-restore backup, closes the live connection, swaps files atomically, and reopens (migrating an older-schema backup forward behind its own pre-migration backup). An invalid backup never replaces current data; every failure reports a typed recovery state.
  • Recovery screen — lists valid local backups and restores one after explicit confirmation; works even when storage would not open.

Acceptance criteria coverage

  • ✅ At most one automatic backup per day — automatic_backup_runs_at_most_once_per_day_and_only_after_data_changes
  • ✅ Unchanged data creates no redundant backup — same test (unchanged-day assertion)
  • ✅ Retention keeps seven automatic backups deterministically — retention_keeps_the_latest_seven_automatic_backups
  • ✅ Every migration preceded by a valid backup or aborts — a_pending_migration_is_preceded_by_a_pre_migration_backup, a_migration_aborts_without_changing_schema_when_the_pre_migration_backup_fails
  • ✅ Restore validates integrity/checksum/schema before replacement — a_checksum_mismatch_is_rejected_before_restore, a_corrupt_sqlite_file_is_rejected, an_unsupported_schema_version_is_rejected
  • ✅ Restore creates a recoverable pre-restore backup and reopened state matches the selected backup — restore_replaces_the_database_and_reopens_to_match_the_backup
  • ✅ Injected failures preserve current database and present typed recovery state — a_failed_pre_restore_backup_preserves_the_current_database, a_replacement_with_a_tampered_source_preserves_the_current_database, replace_database_restores_the_live_file_when_the_target_disappears
  • ✅ No upload, encryption, or out-of-app-data paths — scope fence respected

Testing decisions coverage

WAL-active backup, retention, unchanged day, checksum mismatch, corrupt SQLite, unsupported schema, failed pre-restore backup, failed replacement, successful reopen, and migration backup ordering + abort are each covered by a named test. A deterministic clock is supplied via the now parameter and a temporary app-data directory is used per test.

Notes

  • The spec says "local calendar day"; Nodepad uses the UTC day of the same fixed-width UTC timestamp the durable layer writes everywhere, so the gate stays deterministic and consistent with the codebase. The difference only matters near UTC midnight and never weakens the once-per-day cap. Documented in day_of and the simplicity audit.
  • Simplicity audit (gate: PROCEED) recorded at docs/audits/issue-17-simplicity-audit.md.
  • fallow audit and the two-axis code review both report zero introduced findings; the only fallow complexity finding is the pre-existing App component (introduced: false), out of scope.

Gates

npm run typecheck, npm run lint (max-warnings 0), cargo test --lib (177 passed), 8000 and cargo check all pass.

Do not merge without review.

Local rotating backup, restore, and migration safety for the durable
SQLite database. Backups live in the macOS application-data folder under a
`backups` subdirectory, are produced with SQLite-safe `VACUUM INTO` semantics
(never a naive copy of a live WAL database), and carry a JSON manifest with
schema version, created time, app version, sha256 checksum, and backup kind.

- `src-tauri/src/backup.rs` owns backup creation, validation (checksum +
  integrity + supported schema), retention (seven automatic; four each
  pre-migration/pre-restore), a full-scan data fingerprint, and atomic file
  replacement that preserves the current database on any failure.
- `WorkspaceStore::open_with_backup` guards every pending migration with a
  verified pre-migration backup or aborts without migrating. The migrations
  list is extracted so the pending count and the migrator share one source.
- `WorkspaceStore::maybe_automatic_backup` runs at most once per local
  calendar day, only after durable data changed since the last backup.
  Tracking state lives in a sidecar file so recording it never changes the
  fingerprint it compares against.
- The `restore_backup` command re-validates the selected backup, makes a
  pre-restore backup, closes the live connection, swaps files atomically, and
  reopens (migrating an older-schema backup forward behind its own pre-
  migration backup). An invalid backup never replaces current data.
- The recovery screen lists valid local backups and restores one after
  explicit confirmation; it works even when storage would not open.

Closes #17.
- Drop the FTS virtual table from the fingerprint (it duplicated the notes
  signal the comment said was being avoided) by excluding the whole
  note_search family.
- Simplify integrity_check's open-failure mapping to |_| BackupError::Corrupt.
- Document the UTC-day decision in day_of and the simplicity audit; the
  audit now reflects the backup-state.json sidecar, not app_preferences rows.
- Import WorkspaceSnapshot at the top of storage-recovery.tsx and restore
  the trailing newline.
- Add the two missing scenario tests: a failed pre-restore backup preserves
  the current database, and a tampered-source replacement preserves the
  current database.
- Remove the unused backup_count test helper.
@kiran-brahma
kiran-brahma merged commit c59e8f8 into main Jul 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

V0-16: Add rotating backup, restore, and migration safety

1 participant

0