WPHammer
Log in

Snapshots

Snapshots are point-in-time captures of a site's database and optionally its files, stored directly on the server filesystem. They are the fastest backup type — no data leaves the server, so they complete quickly and restore instantly. Use snapshots before risky operations where you want a quick undo.

Snapshot types

The SnapshotType enum defines two modes:

  • Database Only (DbOnly) — exports the WordPress database using wp db export. Fast and lightweight, suitable for protecting against content or configuration changes.
  • Full (Full) — exports the database and creates a tar.gz archive of the site files. Use this when you need to protect both data and code, such as before a plugin update or theme change.

Creating snapshots

The CreateSnapshotAction creates a Snapshot record and dispatches the CreateSnapshotPipeline, which runs a single step:

The CreateSnapshotJob connects via SSH and:

  1. Creates a snapshot directory at /home/{user}/{site}/wph-snapshots/{timestamp}-{label}/
  2. Exports the database: wp db export {snapshot_dir}/database.sql
  3. For full snapshots, archives files: tar -czf {snapshot_dir}/files.tar.gz .
  4. Records the server_path and size_bytes on the snapshot

Snapshots can optionally include a label for identification — for example, "Before plugin update" or "Pre-staging push".

Restoring snapshots

The RestoreSnapshotAction dispatches the RestoreSnapshotPipeline, which runs a single step:

The RestoreSnapshotJob connects via SSH and:

  1. Imports the database: wp db import {snapshot_dir}/database.sql
  2. For full snapshots, extracts files: tar -xzf {snapshot_dir}/files.tar.gz
  3. Flushes the WordPress cache: wp cache flush
  4. Updates restored_at on the snapshot record

Snapshot restores do not create a pre-restore safety backup — they prioritize speed over safety nets. If you need a safety net, create a second snapshot before restoring.

Snapshot status

The status field uses the BackupStatus enum:

  • Pending — snapshot created but not yet started
  • Running — the export is in progress
  • Completed — snapshot is ready and available for restore
  • Failed — the snapshot could not be created

Storage

Snapshots live on the server at /home/{user}/{site}/wph-snapshots/. This means:

  • They do not require a storage provider or S3 credentials
  • They are available immediately without downloading
  • They consume disk space on the server
  • They are lost if the server is destroyed or its disk fails

For durable, off-server backup, use database backups or time capsules.

When to use snapshots

Snapshots are best suited for:

  • Pre-deployment safety — create a snapshot before running a deployment pipeline
  • Before risky changes — plugin updates, WP-CLI commands, search-and-replace operations
  • Before staging pushes — the staging push pipeline creates a safety backup automatically, but an explicit snapshot gives you direct control
  • Quick testing — snapshot, make changes, evaluate, restore if needed

They are not suited for disaster recovery (server-local only) or long-term archival (no off-site copy).

Related