Migrations and upgrades

When to use it

Use this skill for schema and data changes: dbDelta tables, versioned migrations, batched backfills, partial failures, multisite and HPOS transitions, search-replace, PHP or WordPress version upgrades, and rollback readiness. HPOS is the WooCommerce high-performance order storage. A backfill is a job that rewrites existing data in batches.

Other skills for nearby topics

• WP-CLI runbook steps: wp-devkit-wpcli-and-ops.
• Plugin activation and hook lifecycle design: wp-devkit-plugin-development.
• WooCommerce order API details: wp-devkit-woocommerce-dev.
• Release pipeline and package rollback: wp-devkit-ci-cd-and-release-engineering.
• Query speed of the backfill: wp-devkit-performance-review.

Run a review in Claude

With the plugin loaded, start a read-only review of one bounded target:

/wp-devkit:migration-review <target-path>

The short form /wp-devkit:migration asks for a quick scan.

Run a review in Codex, ChatGPT or Antigravity

Name the installed skill and keep the request small. Replace the target with your files or the journey you care about.

$wp-devkit-migration-upgrade-review
Review the target without editing files.
Read the project instructions and the skill's engineering contract first.
Separate confirmed findings from candidates and state the evidence and checks you could not run.

The engineering contract is the set of rules every DevKit skill follows, such as how severity is graded and what counts as evidence.

Reference files

The agent loads only the file that matches your task:

• schema-and-dbdelta.md applies to any table or column change. It covers dbDelta rules and limits, collation, indexes, the cost of online DDL, schema versions and the expand/contract pattern.
• backfill-and-batching.md applies to data rewrites and large tables. It covers cursors, batch size, idempotency, locks, checkpoints, verification, and Action Scheduler and WP-CLI runners.
• multisite-and-storage-transitions.md applies to multisite, WooCommerce orders and URL or domain changes. It covers network and site upgrades, new-site hooks, HPOS migration, serialized data, search-replace, and option, meta and post-type changes.
• platform-upgrades-and-rollback.md helps with upgrade planning and recovery. It covers WordPress, PHP and MySQL upgrades, the limits of auto-update rollback, backups and restore drills, and uninstall and downgrade policy.
• migration-upgrade-review-workbook.md holds symptom triage, worked decisions, look-alikes that are not defects, and verification steps.

How a review runs

1. The agent states the invariant, which is what must be true of the data after the migration. It lists the old and new representations, the authoritative storage, the site scope, and every writer and reader that may run at the same time (old code, new code, WP-CLI, cron, REST).
2. It finds the trigger and the completion marker. Activation hooks do not run on ordinary updates. The update path must compare a stored version on a hook that does run for updates, typically plugins_loaded or init, and it must also cover manual, auto-update and multisite paths. The version is recorded only after the invariant holds.
3. It checks schema changes. They must be additive and compatible while old and new code overlap. The agent reviews the dbDelta formatting, the resulting indexes and types, engine behavior and lock time at the real table size. MySQL and MariaDB commit DDL implicitly, so wrapping it in a transaction gives no rollback.
4. It checks the backfill: a stable selection and cursor, batches bounded by rows and time, resumability, idempotency, what happens when eligibility changes mid-run, treatment of invalid historic values, concurrency control (a lock with an owner and an expiry) and progress saved after committed work.
5. It checks cutover and recovery. Reads and writes stay compatible until verification passes, using counts, checksums or sampled values. The agent asks what restoring old code does (nothing to the data), whether a backup and restore was rehearsed, and whether the contract phase is deferred to a later release.
6. It checks scope: per-site or network, HPOS or legacy order storage, serialized data, uninstall behavior and the supported WordPress and PHP range.
7. It reports findings with a reproduction on a disposable dataset where possible. Otherwise a finding stays a candidate, with the missing evidence named. The workbook holds the severity rules, the finding template, false positives and acceptance checks.

What you get back

The report leads with the verdict and the reviewed scope. Each finding lists its severity, file:line, the trigger (install, update, manual run, multisite or concurrent worker), the failure path, the data impact, confidence, a minimal fix and a regression test. Candidates and missing evidence are listed apart.

The report also lists executed checks with command and exit status, and unexecuted ones such as a production-size run, a real restore or concurrent workers. For implementation work it adds the stages, the verification queries and their results, and rollback instructions. Being able to roll back the code is never presented as data recovery.

Where to go next

Use review to fix to turn findings into a bounded change. Use Doctor and reports for environment checks and evidence tooling.