Restore Guide

Overview

SafeGuard's restore engine lets you bring your WordPress site back to a known good state in minutes. Whether you need to recover from a hack, undo a failed plugin update, or roll back a database change, the restore process is designed to be safe, fast, and reversible.

Common scenarios where you would restore:

• Hacked or compromised site — revert to a clean backup taken before the breach
• Failed update — a plugin, theme, or WordPress core update broke your site
• Accidental data loss — deleted content, media, or configuration changes you need to undo
• Testing and experimentation — restore to a known baseline after trying out changes
• Migration issues — roll back a migration that did not go as planned

SafeGuard restores are resumable — if a restore is interrupted by a server timeout or crash, it picks up where it left off on the next run. During the restore, your site is placed in maintenance mode so visitors see a friendly message instead of a broken page.

Before You Restore

Run through this checklist before starting a restore:

• Backup exists and is accessible — confirm the backup you want to restore from appears in SafeGuard → Backups with a "Completed" status
• Backup integrity — SafeGuard runs an automatic integrity check (ZIP validation) during preflight, but you can verify manually by clicking the backup and checking its details
• Sufficient disk space — the restore requires approximately 2x the backup size plus 1 GB of free space for extraction and temporary files
• No other restore in progress — only one restore can run at a time; SafeGuard enforces this with an exclusive lock
• Incremental chain intact — if restoring from an incremental backup, the parent (full) backup and all intermediate incremental backups must be available
• Note your current state — consider running a quick backup before restoring so you can get back to your current state if needed

SafeGuard runs automated preflight checks before every restore that verify disk space, backup integrity, storage accessibility, and incremental chain completeness. If any check fails, the restore is blocked with a clear error message.

Restoring from the Dashboard

# Run preflight checks first
wp safeguard restore preflight 42

# Start a full restore (--yes skips the confirmation prompt)
wp safeguard restore run 42 --yes

# Restore only the database
wp safeguard restore run 42 --scope=database --yes

# Restore only files (themes, plugins, uploads)
wp safeguard restore run 42 --scope=files --yes

wp safeguard restore run 42 --dry-run

# Restore but skip file pruning entirely
wp safeguard restore run 42 --skip-prune --yes

# Force pruning even if the number of files to delete exceeds the safety threshold
wp safeguard restore run 42 --force-prune --yes

# Also prune the uploads directory (dangerous — removes user media not in the backup)
wp safeguard restore run 42 --include-uploads --yes

# Check restore status while it is running
wp safeguard restore status

# Cancel a restore in progress
wp safeguard restore cancel --yes

wp safeguard restore run 42 --force --yes

Selective Restore

Not every situation requires a full restore. SafeGuard lets you restore specific components of your site independently.

Database Only

Restores all WordPress database tables — posts, pages, comments, options, user data, plugin settings, and custom tables. Files on disk are left untouched.

When to use:

• Accidentally deleted posts or pages
• A plugin corrupted your options table
• You need to revert WooCommerce orders or customer data
• Database migration went wrong

wp safeguard restore run 42 --scope=database --yes

Files Only

Restores all files — WordPress core, themes, plugins, and uploads — without touching the database. Useful when files were corrupted or modified but your content is intact.

When to use:

• Malware injected files into your WordPress installation
• A theme or plugin update corrupted files
• You accidentally modified core WordPress files
• File permissions were changed and broke your site

wp safeguard restore run 42 --scope=files --yes

Protected Files

During any file restore, SafeGuard automatically protects critical configuration files that should not be overwritten:

These files are never overwritten during a restore, even in full restore mode.

Restoring from Incremental Backups

Incremental backups only contain files that changed since the last backup. When you restore from an incremental backup, SafeGuard automatically rebuilds the complete state by chaining together the full (parent) backup and all subsequent incremental backups in order.

How it works:

1. SafeGuard identifies the incremental backup's parent (the most recent full backup in the chain)
2. It verifies all backups in the chain exist and pass integrity checks
3. The full backup is extracted first as the base layer
4. Each incremental backup is applied on top, in chronological order
5. The final result is a complete point-in-time snapshot of your site

Example chain:

Restoring from backup #41 (Thursday) automatically applies #38, then #39, #40, and #41 in sequence to reconstruct Thursday's state.

File Quarantine

When SafeGuard restores files, it does not simply delete the files it replaces. Instead, replaced files are moved to a quarantine directory at wp-content/safeguard-quarantine/. Each restore creates a timestamped subfolder (e.g., 20260328-140523) containing all the files that were overwritten.

This means you can recover individual files after a restore without needing to do a full rollback.

Quarantine lifecycle

• Created — automatically during every file restore
• Retained — for 7 days after the restore
• Expired — SafeGuard's daily maintenance task automatically deletes quarantine folders older than 7 days
• Manual cleanup — you can delete quarantine folders early from the dashboard or CLI if you need to free disk space

Managing quarantine

# List all quarantine folders
wp safeguard quarantine list

# Restore files from a specific quarantine folder
wp safeguard quarantine restore 20260328-140523

# Delete a specific quarantine folder
wp safeguard quarantine purge 20260328-140523

# Delete all quarantine folders
wp safeguard quarantine purge --all --yes

Rollback

If a restore does not go as expected, SafeGuard provides two ways to get back to your pre-restore state.

Pre-restore snapshot (recommended)

When you enable Create pre-restore snapshot before starting a restore, SafeGuard takes a full backup of your current site first. If the restore produces unexpected results, you can restore from this snapshot to return to exactly where you were before.

# The restore output shows: "Pre-restore snapshot: #55"
wp safeguard restore run 55 --yes

Automatic error handling

If a restore fails mid-process (due to a file permission error, database issue, or unexpected exception), SafeGuard automatically:

1. Stops the restore process
2. Disables maintenance mode so your site comes back online
3. Logs the error with full details for debugging
4. Preserves the quarantine folder so replaced files can be recovered
5. Releases the restore lock so you can attempt another restore

Your site will be in a partial state — some files or tables may have been restored while others have not. This is why the pre-restore snapshot is strongly recommended for production sites.

wp safeguard restore cancel --yes

Post-Restore Checklist

After a restore completes, verify everything is working:

• Homepage loads — visit your site's homepage and confirm it renders correctly
• Admin dashboard works — log into wp-admin and check for errors
• Plugins are active — go to Plugins and confirm expected plugins are activated
• Theme is correct — check Appearance → Themes to verify the active theme
• Content is intact — spot-check a few posts, pages, and media items
• Forms and interactive features work — test contact forms, search, and other dynamic functionality
• Permalinks work — if you see 404 errors, go to Settings → Permalinks and click Save Changes to flush rewrite rules
• Cron and schedules — verify your SafeGuard backup schedules are still active under SafeGuard → Schedules
• SSL and URLs — if you used URL replacement, confirm all pages load over the correct protocol without mixed-content warnings
• E-commerce — if you run WooCommerce or another shop plugin, place a test order to confirm the checkout flow

Troubleshooting

If you continue to have issues, enable debug logging under SafeGuard → Settings → Advanced and check the log at wp-content/safeguard/logs/restore.log for detailed error messages.