feat(db): snapshot and restore the shared Postgres (spec 15)

[gustavobertoi]

What

Graduates the spec-15 data-lifecycle verbs for the shared Postgres (thin v2 scope: Postgres-only, per-project tenant):

• devstack db snapshot [name] — capture the project's tenant database
• devstack db snapshot ls — list captured snapshots (lock-free)
• devstack db restore <name> — replay a snapshot into the tenant (destructive; confirm/--yes, refuses non-empty without --force)

db reset / db pull remain reserved v2 stubs.

How

• New internal/db seam: a Dumper interface + PgDumper that shells pg_dump/pg_restore/psql behind an injectable Runner. The release binary stays CGO-free (external tools). The password rides PGPASSWORD in the process env, never on the argv. Preflight maps a missing client tool to a one-line remediation, and degrades the db verbs only (never blocks up).
• internal/orchestrate/snapshot.go reuses the exact provision host-reachability pattern — engineTarget → FreeHostPort + writeProvisionOverlay + compose up -d <inst> on the shared stack — so the dump/restore tooling reaches the warm Postgres over a ledger-allocated 127.0.0.1 host port without publishing a permanent one. Per spec 15, the dump/restore process runs outside the flock; only the ledger row + event write are locked.
• Dumps + a JSON sidecar land under $DEVSTACK_HOME/snapshots/<workspace>/<name>.dump (store.SnapshotsPath). Each snapshot is recorded as a provisioned(kind=snapshot) ledger row plus a db.snapshot/db.restore event — the kind column is free-text, so no migration is needed.
• Restore re-hashes the dump for integrity, refuses a non-empty tenant without --force, and honors --project / --db / --instance. --json/--quiet contract throughout.

Testing

CGO_ENABLED=0 go build ./..., CGO_ENABLED=1 go test ./internal/..., gofmt -l (clean), go vet ./... — all green. No internal/generate or templates/ changes, so determinism is unaffected.

New tests (no real Postgres):

• snapshot → restore round-trip via a mock runner — asserts pg_dump/pg_restore argv, PGPASSWORD-in-env (no argv leak), the host-port overlay allocation (ledger port_alloc row + compose up of the overlay), and the snapshot ledger row.
• restore refusal without --force on a non-empty tenant (and success under --force).
• non-TTY --json shape (documented keys), ls, and the PgDumper argv + Preflight remediation.

🤖 Generated with Claude Code