README
¶
RestoreLab
Recovery drill verification for PostgreSQL backups.
RestoreLab answers one question:
Can I actually restore this archive right now, in isolation, without touching production?
It is not a backup tool. It is a verification layer on top of Restic that restores a PostgreSQL archive inside a hardened, disposable Docker container, runs your SQL checks against it, and prints a report showing exactly what was and was not tested.
Scope of v0.1.0
Supported:
- Restic repositories
- PostgreSQL (custom-format dumps)
- Docker Engine
- CLI with JSON + HTML reports
Not supported in v0.1.0:
- Borg, PBS, Duplicati
- MySQL, MariaDB, SQLite
- Kubernetes, Podman
- Web UI, scheduler, alerts
Anything not in the supported list is deliberately deferred to ROADMAP.md and will not enter v0.1.0.
Why
A successful backup job only proves the file exists. It does not prove the workload can actually recover. Restic's check verifies repository integrity, and tools like Veeam SureBackup distinguish between integrity check and boot-it-in-an-isolated-lab. RestoreLab applies that idea to Docker-based PostgreSQL backups.
Prerequisites
- Docker Engine 26.0.0+ (fixes CVE-2024-29018)
- Restic 0.14.0+ (0.17.0+ recommended for size metadata)
- Go 1.22+ if building from source
- PostgreSQL image pinned by digest
Real-world validation
See docs/REAL-WORLD-VALIDATION.md for findings from testing RestoreLab against real HomeLab backups, including how two issues with custom database images were found and fixed.
Build
git clone https://github.com/YOUR-USERNAME/restorelab cd restorelab go build -o restorelab ./cmd/restorelab
On Debian/Ubuntu, the Docker SDK requires CGO. See docs/BUILD_REQUIREMENTS.md.
Validate a contract
export RESTIC_REPOSITORY=/path/to/repo export RESTIC_PASSWORD_FILE=/path/to/password.txt export TEST_DB_PASSWORD=throwaway-password
./restorelab validate examples/postgres-restic.yaml
Run a drill
./restorelab run examples/postgres-restic.yaml
--json=report.json
--html=report.html
Open report.html in a browser to see every stage and check.
Security properties
- cap_drop ALL, cap_add minimal set
- no-new-privileges true
- read-only root filesystem
- no published ports
- no privileged mode
- no Docker socket mount
- internal network only
- artifact bind-mounted read-only
- memory, PIDs, and shm bounded
- cleanup guaranteed via defer
See SECURITY.md for the full threat model.
Exit codes
0 success (overall PASS or WARNING) 1 failure (contract invalid, drill failed, runtime error) 2 usage error
Roadmap
- v0.2.0: MariaDB support
- v0.3.0: Borg provider
- v0.4.0: Proxmox Backup Server
- v1.0.0: Optional web UI, scheduling, alerts
License
MIT. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
restorelab
command
Command restorelab is the CLI entry point for RestoreLab.
|
Command restorelab is the CLI entry point for RestoreLab. |
|
internal
|
|
|
contract
Package contract defines the recovery contract schema for RestoreLab.
|
Package contract defines the recovery contract schema for RestoreLab. |
|
engines
Package engines defines the DatabaseEngine interface implemented by every supported database backend.
|
Package engines defines the DatabaseEngine interface implemented by every supported database backend. |
|
engines/postgres
Package postgres implements the engines.DatabaseEngine interface for PostgreSQL.
|
Package postgres implements the engines.DatabaseEngine interface for PostgreSQL. |
|
preflight
Package preflight validates the runtime environment before any restore operation begins.
|
Package preflight validates the runtime environment before any restore operation begins. |
|
providers
Package providers defines the BackupProvider interface that all backup backends must implement.
|
Package providers defines the BackupProvider interface that all backup backends must implement. |
|
providers/restic
Package restic implements the providers.BackupProvider interface for Restic repositories.
|
Package restic implements the providers.BackupProvider interface for Restic repositories. |
|
report
Package report defines the structure and rendering of RestoreLab recovery drill reports.
|
Package report defines the structure and rendering of RestoreLab recovery drill reports. |
|
sandbox
Package sandbox manages the isolated Docker environment in which a restored PostgreSQL database is started and validated.
|
Package sandbox manages the isolated Docker environment in which a restored PostgreSQL database is started and validated. |
|
workflow
Package workflow orchestrates a single recovery drill end-to-end: preflight checks, Restic restore, sandbox creation, PostgreSQL restore, SQL validation, reporting, and cleanup.
|
Package workflow orchestrates a single recovery drill end-to-end: preflight checks, Restic restore, sandbox creation, PostgreSQL restore, SQL validation, reporting, and cleanup. |