Snapshots & Rollback

Overview

Snapshots capture a full copy of your WordPress database and a manifest of active plugin and theme files before risky operations. If something goes wrong after an update, activation, or theme switch, you can roll back to the exact state the site was in moments before the change.

What Gets Captured

Each snapshot produces two files stored in a timestamped directory:

1. Database dump (database.sql)

A full SQL export of all WordPress tables (those matching {prefix}%). The export includes DROP TABLE IF EXISTS and CREATE TABLE statements followed by INSERT statements for every row. Rows are exported in batches of 500 to manage memory on large databases.

-- AdminLocks Snapshot
-- Date: 2026-03-05 14:22:10

DROP TABLE IF EXISTS `wp_posts`;
CREATE TABLE `wp_posts` ( ... );

INSERT INTO `wp_posts` VALUES ('1','My First Post', ...);
INSERT INTO `wp_posts` VALUES ('2','About Us', ...);
-- ... batched in groups of 500 rows

2. File state manifest (files.json)

A JSON document containing MD5 checksums of all active plugin main files and metadata about the active theme. This is not a full file backup but rather a fingerprint that lets you detect what changed.

{
    "plugins": {
        "woocommerce/woocommerce.php": "a1b2c3d4e5f6...",
        "adminlocks/adminlocks.php": "f6e5d4c3b2a1...",
        "contact-form-7/wp-contact-form-7.php": "1a2b3c4d5e6f..."
    },
    "theme": {
        "stylesheet": "astra",
        "template": "astra",
        "version": "4.6.1"
    }
}

Automatic Triggers

AdminLocks automatically creates snapshots before three categories of risky operations. These hooks run at priority 5 to ensure the snapshot is created before the change begins.

Each auto-snapshot is labeled with a descriptive prefix so you can identify the trigger when browsing your snapshot history. For plugin changes, the label includes the plugin file path for precise identification.

Manual Snapshots

You can create snapshots on demand through the REST API. This is useful before making manual changes like editing wp-config.php, running database migrations, or deploying custom code.

// POST /wp-json/adminlocks/v1/snapshots
{
    "label": "Pre-deployment snapshot"
}

// Response
{ "id": 15 }

Manual snapshots use the trigger event manual in the database record, making them easy to distinguish from automatic ones.

Restoring a Snapshot

Restoring a snapshot imports the saved SQL dump back into the database, effectively reverting all table data to the captured state. The restore process follows a safety-first approach:

1. Safety snapshot — before restoring, AdminLocks automatically creates a new snapshot labeled "Pre-restore safety snapshot" with trigger event auto_pre_restore. This ensures you can undo the restore if needed.
2. Database import — the SQL file is read and each statement is executed. DROP TABLE statements replace existing tables, and INSERT statements repopulate the data.
3. Audit logging — the restore action is logged to the audit log with severity warning.

Snapshot statuses

Storage & Cleanup

Snapshots are stored on the WordPress server at:

wp-content/uploads/adminlocks-snapshots/{YYYYMMDD-HHiiss}/
    database.sql
    files.json

Directory protection

The base snapshot directory is automatically protected with two files:

• .htaccess containing Deny from all to block direct web access on Apache servers.
• index.php containing the standard WordPress "Silence is golden" guard to prevent directory listing.

Expiration

Every snapshot is created with an expires_at timestamp set to 30 days from creation. A daily cron job (adminlocks_snapshot_cleanup) checks for expired snapshots and deletes them, including their files on disk.

Disk usage

The REST API includes a disk_usage_bytes field in the snapshot list response, showing the total size of all stored snapshots. You can use this to monitor storage consumption and decide when to manually delete old snapshots.

// GET /wp-json/adminlocks/v1/snapshots response includes:
{
    "items": [ ... ],
    "total": 12,
    "disk_usage_bytes": 52428800  // ~50 MB
}

REST API

The snapshot system exposes four REST endpoints. All require the manage_options capability.

List response format

// GET /wp-json/adminlocks/v1/snapshots
{
    "items": [
        {
            "id": 15,
            "label": "Pre-deployment snapshot",
            "trigger_event": "manual",
            "status": "complete",
            "db_path": "/var/www/html/wp-content/uploads/adminlocks-snapshots/20260305-142210/database.sql",
            "files_path": "/var/www/html/wp-content/uploads/adminlocks-snapshots/20260305-142210/files.json",
            "size_bytes": 4521984,
            "created_by": 1,
            "expires_at": "2026-04-04 14:22:10",
            "created_at": "2026-03-05 14:22:10"
        }
    ],
    "total": 12,
    "disk_usage_bytes": 52428800
}