feat: Pre-deploy volume snapshots and backup/restore CLI for databases

[ameistad]

Haloy manages database containers end-to-end (create, deploy, health check, proxy, delete) but has no data protection. A bad deploy, wrong image version, broken migration, or bad config change can destroy data with no way to roll back. The preset: database sets protected: true, but that only prevents accidental deletion.

This adds two things: automatic volume snapshots before each database deploy, and CLI commands for manual backup and restore.

How it works

Before stopping the current database container during a replace strategy deploy, the daemon copies the volume data to a timestamped snapshot directory. Since replace stops the container first, the database has flushed its WAL and shut down cleanly, so the filesystem copy is consistent.

The copy runs through a temporary container:

docker run --rm -v SOURCE:/source -v DEST:/dest busybox cp -a /source/. /dest/

Snapshot metadata (app name, deployment ID, volume name, path, timestamp, size) goes into SQLite. Old snapshots get pruned by retention count.

New CLI commands follow the existing patterns (haloy deploy, haloy rollback, haloy logs):

haloy backup <app> # Snapshot the app's volumes
haloy backup list <app> # List available snapshots
haloy restore <app> <backup-id> # Restore from a specific snapshot
haloy backup prune <app> # Remove old snapshots beyond retention

Config

targets:
 postgres:
 preset: database
 image:
 repository: postgres:18
 port: 5432
 volumes:
 - postgres-data:/var/lib/postgresql/data
 backup:
 pre_deploy_snapshot: true # default: true for database preset
 snapshot_retention: 3 # keep last 3 snapshots, default: 3

Server-level in haloyd.yaml:

backups:
 snapshot_dir: /var/lib/haloy/snapshots # default location

Implementation plan

Config (internal/config/)

• deploy_config.go: Add Backup struct to TargetConfig with PreDeploySnapshot *bool and SnapshotRetention *int
• deploy_config_validate.go: Validate retention > 0

Config loading (internal/configloader/)

• loader.go: Set defaults in applyPreset() for database preset (pre_deploy_snapshot: true, snapshot_retention: 3). Handle Backup field merging in MergeToTarget()

Backup logic (new internal/backup/)

• snapshot.go: Volume snapshot and restore via Docker SDK. Temporary container mounts source volume + snapshot destination, copies data. Restore does the reverse.
• prune.go: Delete oldest snapshots beyond retention count.

Storage (internal/storage/)

• migrations.go: Add snapshots table
• models_snapshots.go (new): SQLite operations for snapshot metadata (id, app_name, volume_name, deployment_id, path, created_at, size_bytes)

Deploy integration (internal/deploy/)

• deploy.go: Before the container stop/remove block for replace strategy (~line 37), snapshot all volumes if backup config is enabled. Prune old snapshots after successful deploy.

API (internal/api/)

• routes.go: Add POST /v1/backup/{appName}, GET /v1/backup/{appName}, POST /v1/restore/{appName}/{backupId}, DELETE /v1/backup/{appName}/{backupId}
• handlers_backup.go (new): Backup/restore handlers, streaming progress via SSE (same pattern as deploy).

CLI (new)

• cmd/backup.go: haloy backup and haloy backup list
• cmd/restore.go: haloy restore
• cmd/backup_prune.go: haloy backup prune

Scope

This is a filesystem-level safety net for deploy-time failures, not a replacement for pg_dump, WAL archiving, or managed database backups.

• Snapshots are full volume copies, no dedup or compression
• Disk usage scales with retention * volume_size
• Pre-deploy snapshots cover deploy failures; haloy backup covers everything else
• No scheduled backups or database-aware dumps (separate features if needed)

Testing

• Config validation (valid/invalid retention, preset defaults)
• Config merging (global backup config + target override)
• Snapshot metadata SQLite operations (create, list, delete, prune)
• Volume snapshot round-trip (create data, snapshot, modify, restore, verify)
• Existing deploy flow unaffected when pre_deploy_snapshot: false

[shyim]

Maybe worth here to start an brother abstraction more like Heroku Addon style or Upsun's Services: https://developer.upsun.com/docs/add-services/postgresql/index

because per service you want kinda different way of handling of backup, may different handling of version upgrades 👀 . Depends also on how much you gonna want to abstract it to the users tbh. Just commting here as an idea :)