MODX Core and Manager Upgrade: Recovering Safely When a Mid-Upgrade Failure Leaves Partial Schema Changes

Question

ContextWe run MODX (assume a current Revolution 3.x line, please note if behavior differs) and are planning our upgrade runbook. The upgrade is driven by PHP setup scripts that touch both the file system and the database schema, and my understanding is that if one step fails, the process halts without automatically reverting the steps that already succeeded.The interoperability concernAt the boundary between the Core upgrade scripts and the Manager, the Manager appears to log the last successful step and offers a manual rollback path, but there seems to be no transactional wrapping of schema changes and no automatic pre-upgrade database snapshot. That raises the risk of a half-migrated schema coexisting with newly written template or core files from the aborted run.Unresolved questionsIs the manual rollback option in the Manager guaranteed to reverse all schema mutations applied before the failure point, or can partial changes persist silently?Do leftover file-system artifacts from a failed upgrade need to be removed before re-running setup, and does the installer detect them?Is a full database and file backup before every upgrade the only community-endorsed safe recovery strategy, or is there a supported snapshot mechanism I have missed?

Tasadduq Burney · Answer

Confirmed factsMODX Revolution’s upgrade runner executes plain SQL statements through xPDO without wrapping them in a transaction. Therefore any schema changes that have already run remain in the database when the process aborts. The Manager's Rollback button only works if a pre‑upgrade backup (database dump + file archive) was created via Tools → Backup before starting the upgrade; it restores that backup and does not revert individual migration steps.Likely explanationBecause there is no automatic snapshot or transactional safety net, a mid‑upgrade failure leaves two kinds of leftovers: (1) schema alterations that were already applied, and (2) new or modified core/manager files that were extracted by the installer. The Manager cannot infer which files belong to the failed run, so leftover files must be cleared manually before a retry.Recovery stepsDetermine whether a pre‑upgrade backup exists (see diagnostic question below).If a backup exists:In the Manager go to Tools → Backup → Restore and select the pre‑upgrade backup.Verify the restored database matches the backup checksum (optional but recommended).Delete or rename the setup/ directory so the installer does not re‑run the same scripts.Address the cause of the original failure (e.g., PHP version, missing extensions) and then re‑run the upgrade from /setup/.If no MODX‑generated backup was made:Restore your own full database dump taken before the upgrade.Replace the entire MODX file tree with the original version you were running (or restore a file‑system snapshot).Ensure the setup/ directory is absent.Retry the upgrade after fixing the failure cause.To confirm which recovery path to follow, please verify whether you created a pre‑upgrade backup via the Manager’s Tools → Backup before launching the upgrade.

MODX Core and Manager Upgrade: Recovering Safely When a Mid-Upgrade Failure Leaves Partial Schema Changes

Context

The interoperability concern

Unresolved questions

1 answer

Confirmed facts

Likely explanation

Recovery steps

Your perspective belongs here.

0 question comments