fix(backup): validate restored database before replacing live state

[MisterWanted]

Summary

• Recover the narrow restore-safety change from archived rescue commit ce10c2d, adapted to current main.
• Validate/upgrade only the verified staging copy before creating the safety backup or replacing live state; wrap validation rejection as BackupError.
• Keep existing rollback, cache invalidation, and applied-version reporting. No custom database-path, CSP, or workflow changes.

Verification

• Regression reproduction on prior code: 4 failures, 1 pass.
• uv run --frozen ruff check .: PASS.
• uv run --frozen mypy: PASS (114 source files).
• uv run --frozen pytest tests/test_backup_restore_staging.py --no-cov -q: 5 passed.
• no-org-leak and git diff --check: PASS.
• Independent local source review: no P1/P2 in the scoped diff; not GitHub approval credit.

Boundaries

Tests use opaque database bytes and replace both the migrator and SQLite connection entrypoint. No SQL files, migration definitions, real migrations, or live restore/deployment were changed or executed by this slice. Broader existing backup integration tests were not run locally. Remote CI and independent exact-head approval remain required before landing.

Summary by CodeRabbit

• Bug Fixes
  • Restores now validate database migrations before replacing the existing installation.
  • Failed migrations no longer overwrite current data or create unnecessary safety backups.
  • Fresh installations remain unchanged when restored database validation fails.
  • Restore operations without a database bundle continue without running migrations.
  • Failures during safety-backup creation preserve the existing installation.

[coderabbitai]

Warning

Review limit reached

Next included review available in 24 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: dcb2f85c-ea2b-423e-aac6-9b86014a6822

📥 Commits

Reviewing files that changed from the base of the PR and between 0fffd76 and ba5acd6.

📒 Files selected for processing (2)

• src/kater/backup.py
• tests/test_backup_restore_staging.py

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: ac7e395f-26d2-46f8-9137-7abf9afb830d

📥 Commits

Reviewing files that changed from the base of the PR and between 771985b and 0fffd76.

📒 Files selected for processing (2)

• src/kater/backup.py
• tests/test_backup_restore_staging.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

Staged restore validation

Layer / File(s)	Summary
Pre-install migration validation src/kater/backup.py	restore_backup runs migrations on the staged database before installation, records applied versions, and reports migration failures as BackupError.
Restore ordering and failure coverage tests/test_backup_restore_staging.py	Tests verify staged migration ordering, state preservation, safety-backup behavior, cleanup, fresh installs, and bundles without a database.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 0fffd

Backup restores now validate and upgrade the staged database before replacing existing state. Failed validation preserves the current installation, while successful restores install the validated copy and retain applied-version reporting.

Sequence Diagram(s)

sequenceDiagram
  participant restore_backup
  participant staging
  participant migrations
  participant safety_backup
  restore_backup->>staging: Extract restore bundle
  restore_backup->>migrations: Run migrations on staged database
  migrations-->>restore_backup: Return migration results
  restore_backup->>safety_backup: Create safety backup after validation
  restore_backup->>staging: Install validated staged state

Loading

Suggested reviewers: onlinechef

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: validating the restored database before replacing live state.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/backup-restore-before-swap-20260906

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}