Backup restore checks
CJ Ackley | SWE | Project brief

STATUS
Recovery tool brief; backup contract to define. Implementation and tests are planned.

THE PROBLEM
A successful backup job says little about the restored application. This command-line tool restores a PostgreSQL dump and an uploaded-file archive into disposable local resources, checks them together, and produces a report tied to the exact backup set.

DESIGN QUESTION
Can a clean environment recover the data and files needed by the application?

SCOPE
- Use a Python CLI to create an isolated database container and temporary file tree.
- Verify manifests, checksums, referential integrity, and configured read-only application probes.
- Capture failures and timings, then remove only resources created by the run.

CONSTRAINTS
Inputs: A documented dump format and matching file manifest
Isolation: No production credentials or production restore target
Archives: Reject path traversal and unsafe symbolic links
Evidence: Report restore success separately from application checks

ENGINEERING DECISIONS (PROPOSED)
Backup-set consistency and application checks
Treat the database dump, file manifest, and declared snapshot ID as one backup set. Restore into a new disposable environment, then compare records with referenced files and run application probes before reporting success.

ALTERNATIVE
Checksums alone are cheap and useful for detecting byte changes. They do not establish that the restored records and files form a usable application state.

TRADEOFF
Full restores take more time and disk space. Keep a fast checksum stage, but make it visibly different from the recovery result.

PROPOSED TOOLS AND METHODS
Python CLI, PostgreSQL, Disposable containers

VERIFICATION SCENARIO (NOT YET RUN)
Every file is intact, but one belongs to another snapshot
Mix a valid database dump with a valid file set from a different fixture snapshot. Also interrupt the runner after it creates its temporary resources.

PASS CONDITION
The cross-snapshot set fails before receiving a recovery-pass result. Cleanup removes only run-owned resources and leaves an unrelated sentinel container and file intact.

EVIDENCE TO RETAIN
Fixture manifests, read-only consistency queries, a machine-readable run report, and a cleanup test that checks the sentinels.

MEASUREMENT AND LIMITS
Report download, restore, probe, and cleanup durations separately. The drill uses trusted fixture dumps with no production credentials or restore target. It measures a local recovery exercise, not a production recovery-time guarantee.

COMPLETION CRITERIA (PLANNED)
- One command verifies a good set and explains each supplied corrupt-set failure.
- Interrupted runs preserve unrelated resources and can be cleaned up safely.
- A run report identifies the exact input set, tool versions, checks, and timings.

VERIFICATION PLAN
Damaged backup
Truncate a dump or remove a referenced file; report the specific failure.

Cleanup
Interrupt each stage; cleanup must leave unrelated files and containers intact.

Recovery fixtures
Restore a known dataset and compare its expected records and file digests.

PLANNED DELIVERABLES
- Restore CLI with structured and human-readable reports
- Valid, corrupt, and mismatched backup fixtures
- Local runner configuration and a recovery drill guide

SCOPE NOTE
The runner checks a defined backup format and application contract. Results apply to the tested backup set and environment.

NEXT STEP
Define the backup-set manifest and the application checks that matter.
