WPHammer
Log in

Database Backups

Database backups capture your WordPress database through the Laravel Forge backup API. WPHammer ensures a Forge backup configuration exists on each server, triggers backup instances on schedule, and monitors them to completion.

How database backups work

The CreateDatabaseBackupJob handles the full lifecycle:

  1. Verify Forge config — ensures a backup configuration exists on the server in Forge. If none exists, one is created via the Forge API with the server's storage provider and database IDs.
  2. Validate storage — confirms the server has an assigned storage provider. Without one, the backup cannot proceed.
  3. Create instance — calls createBackupInstance() on the Forge API to trigger the backup.
  4. Wait for completion — polls the Forge API for the backup instance status, checking up to 120 times at 5-second intervals (roughly 10 minutes maximum).
  5. Record result — stores the forge_backup_instance_id on the Backup record and updates db_status to Completed or Failed.

Scheduling

Database backups follow the BackupConfig scheduling system. The DispatchScheduledBackupsCommand runs hourly and dispatches backups for configs whose effective hour matches the current UTC hour:

  • Daily — runs every day at the configured hour
  • Weekly — runs on Sundays at the configured hour
  • Manual — only triggered explicitly by a user action

If no preferred_hour is set, the hour is auto-determined using a CRC32 hash of the site ID, distributing backups across the 0–5 AM UTC window.

Each scheduled run creates a Backup record with the label "Scheduled backup" and dispatches it through the BackupSitePipeline.

Database backup status

The db_status field on the Backup model tracks progress using the BackupStatus enum:

  • Pending — backup created but not yet started
  • Running — Forge is executing the backup
  • Completed — backup finished successfully
  • Failed — backup encountered an error
  • Skipped — backup was not needed (e.g., file-only backup)

Storage

Database backups are stored by Forge using the storage provider configured on the server. WPHammer does not handle the actual database dump or upload — Forge manages this entirely. WPHammer's role is to trigger, monitor, and record the result.

The StorageProviderCredential on your team links the Forge storage provider ID to the actual bucket and credentials, which are also used for file backups and time capsules.

Restore points

When a backup completes (via FinalizeBackupJob), a RestorePoint is automatically created. Restore points are the entry point for restoring — each one references the backup it came from and tracks its own lifecycle (Available, Restoring, Restored, Expired).

Monitoring

If a database backup fails, the FinalizeBackupJob sends a BackupFailedNotification to the team owner. The notification includes the site name, backup status, and failure details so you can investigate.

Backup history is visible on the server detail page under the Backups tab, showing status, timestamps, and file sizes for each backup.

Related