Restoring Backups

Listing Available Backups

# List backups available for restore
jokowipe-agent backup list --status success

# ID              STATUS    SIZE      CREATED
# bkp-a1b2c3d4   success   34.1 MB   2024-01-15 02:00:01 UTC
# bkp-b2c3d4e5   success   33.9 MB   2024-01-14 02:00:01 UTC

Restore to Original Database

jokowipe-agent restore --backup-id bkp-a1b2c3d4

This:

1. Downloads the backup from your storage target
2. Runs the restore command (e.g., pg_restore --clean --if-exists)
3. Verifies the restore completed successfully

Data Will Be Overwritten

Restoring to the original database will overwrite all existing data. Make sure you have a recent backup before restoring.

Restore to a Different Database

# Restore to a different database
jokowipe-agent restore \
  --backup-id bkp-a1b2c3d4 \
  --target postgres://user:pass@localhost:5432/mydb_restored

Restore Options

Flag	Default	Description
--backup-id	—	Backup to restore (required)
--target	Original DB	Target database URL
--no-clean	false	Skip DROP before restore (PostgreSQL)
--jobs	4	Parallel restore jobs (PostgreSQL)
--download-only	false	Download file but don't apply
--output-dir	.	Directory for downloaded file
--verify	true	Verify checksum after download

Download Only

Download the backup file without applying it:

jokowipe-agent restore \
  --backup-id bkp-a1b2c3d4 \
  --download-only \
  --output-dir /var/backups/restore

# Downloaded: /var/backups/restore/backup-20240115-020001.dump
# SHA-256: abc123def456...

Verifying a Restore

After restore, verify the database is healthy:

# PostgreSQL — count rows in key tables
jokowipe-agent restore verify \
  --backup-id bkp-a1b2c3d4 \
  --target postgres://user:pass@localhost:5432/mydb

# Output:
# Restore verification for bkp-a1b2c3d4
# Database connection: OK
# Table count: 42 tables
# Row count (sampled): ~2.4M rows
# Verification: PASSED

Point-in-Time Restore

Browse backup history in the dashboard and restore to any available snapshot:

1. Go to Backups in the dashboard
2. Filter by date range to find the desired point in time
3. Select the backup closest to your target time
4. Click Restore

True PITR

PostgreSQL continuous WAL archiving (point-in-time recovery) is on the roadmap. Currently, jokowipe.id supports snapshot-based restore only.

Restore Verification Testing

Set up an automated restore verification job to regularly test your backups:

# In your schedule config
schedule:
  name: "postgres-prod-daily"
  restore_verification:
    enabled: true
    target: "postgres://user:pass@verify-db.internal:5432/verify"
    checks:
      - table_count_min: 30
      - row_count_table: "users"
      - row_count_min: 1000
    notify_on_failure: true

The agent restores the backup to the verification target and runs the configured checks. Results are reported in the dashboard under Backups → Restore Verifications.

Troubleshooting Restores

Permission Denied

ERROR: permission denied for table users

The restore user needs superuser or the appropriate role. For PostgreSQL:

ALTER USER restore_user SUPERUSER;
-- Or grant specific role:
GRANT pg_restore_role TO restore_user;

Disk Space Insufficient

The agent needs enough free space to download the backup before restoring. Check:

df -h /var/tmp/jokowipe

Ensure free space is at least 2x the backup file size.

Version Mismatch

ERROR: pg_restore: error: incompatible server version

The pg_restore version must be equal to or newer than the PostgreSQL server version. See Supported Databases →.