Backup operations: create, list, restore, verify, prune, config, status, init-key.

nself backup <subcommand> [flags] [args]

nself backup covers the full life cycle of project backups: full Postgres dumps, write-ahead-log (WAL) checkpoints, MinIO object snapshots, configuration metadata, and combined backups. Backups can be encrypted with age (one keypair per project) and pruned by retention policy.

Subcommands include create (one-shot full or incremental), list (filter by remote, environment, age), restore (from any backup ID or latest, with partial restore options), verify (checksum or full restore-test in a disposable container), and prune (apply daily/weekly/monthly retention).

Note: Point-in-time recovery (PITR) ships as a dedicated nself pitr command (enable, disable, status, base-backup, restore) in v1.1.1. The --point-in-time flag on backup itself was removed; use nself pitr restore for WAL replay.

backup config --install-cron installs systemd timers for full backups, WAL checkpoints, prune cycles, and weekly verify drills so an operator can hand off to automation.

Note: --point-in-time is not a flag on backup restore. Use nself pitr restore (v1.1.1) for WAL-replay point-in-time recovery via pgbackrest.

When --restore-test is set, backup verify goes beyond the default checksum check:

1. Spins up an ephemeral Postgres container on a random local port.
2. Restores the target .dump file via pg_restore into the container.
3. Runs the full smoke-query catalog (5+ system tables): user table count, live tuple count, auth.users presence, hdb_catalog.hdb_metadata presence, and np_claw_conversations presence. A zero user-table count triggers an explicit "row count mismatch, schema-only restore detected" failure.
4. Runs a sentinel CRUD round-trip: creates a temp schema, inserts a sentinel row, reads it back, and drops the schema. Completes in under 2 seconds. Cleaned up in defer even on panic.
5. Reports pass/fail with JSON output suitable for cron consumption.
6. Tears down the container and volume via defer, cleanup happens even on failure.

Exit code 0 = restore verified. Non-zero = verify failed. JSON output:

{"backup_id":"latest","verified":true,"started_at":"2026-04-20T02:00:01Z","duration":"47.3s","method":"restore-test","details":"file size: 104857600 bytes"}

Use --keep to inspect the restored database before teardown (useful for debugging silent data corruption).

Note: --restore-test is the correct flag (not --test-restore). This is verified in cli/internal/backup/verify.go field RestoreTest.

Cross-link: DR Runbook uses backup verify --restore-test as the weekly automated integrity check.

# Generate the age keypair before first encrypted backup
nself backup init-key

# Create a full encrypted backup tagged for traceability
nself backup create --type full --encrypt --tag pre-deploy

# List backups newer than a week, JSON for piping
nself backup list --since 7d --format json

# Restore latest backup, restoring only Postgres data
nself backup restore latest --only pg --yes

# Verify the latest backup with a real restore-test container
nself backup verify latest --restore-test

# Install systemd timers so backups run automatically
sudo nself backup config --install-cron --full-at 02:30

nself backup creates archives that follow the nself-backup-v1 spec. The spec covers the archive filename pattern, manifest.json structure, checksums.sha256 format, encryption contract, and the exact extraction order used by restore. See .claude/docs/operations/BACKUP-FORMAT.md.

backup create --type metadata exports Hasura metadata by running hasura-cli inside the _hasura container. The Hasura admin secret is passed to docker exec via the -e HASURA_GRAPHQL_ADMIN_SECRET=<value> flag. This keeps the secret in the container's environment and out of the process-table argv, which would otherwise be readable by any local user via ps aux (CWE-214). No user-facing change is required; this is an internal implementation detail.

• cmd-dr, disaster recovery operations
• cmd-secrets, manage encryption keys
• cmd-db, database operations
• Commands, full command index

← Commands | Home →