Upgrading Moodle Core via CLI: A Systematic Procedure

The Problem: Avoiding Web-Based Upgrade Timeouts

Upgrading Moodle via the web interface often leads to browser timeouts or PHP memory limit crashes, especially on sites with large databases or complex plugin sets. When a web-based upgrade hangs mid-process, the database can be left in an inconsistent state, requiring manual intervention or a full restore.

The reliable solution is to use the Command Line Interface (CLI). Running the upgrade via CLI bypasses web server timeouts and provides real-time feedback on database migrations, ensuring the process completes fully before users regain access.

Prerequisites and Environment Validation

Before modifying the codebase, you must verify that your server environment meets the requirements of the target Moodle version. For example, moving to Moodle 4.x typically requires PHP 8.1 or higher and specific database versions (MySQL 8.0+ or PostgreSQL 13+).

• Full Backup: Create a snapshot of the database and a recursive copy of the moodledata directory.
• PHP Version Check: Run php -v on the terminal to ensure the CLI PHP version matches the web server PHP version.
• Plugin Audit: Identify third-party plugins. If a plugin is not yet compatible with the target version, disable it or remove it from the codebase to prevent fatal errors during the upgrade script.

The Upgrade Procedure

Perform these steps as a user with permissions to write to the Moodle directory and execute PHP scripts (typically the www-data or apache user).

1. Enable Maintenance Mode

Prevent users from modifying data while the database schema is changing. Run this from the Moodle root directory:

php admin/cli/maintenance.php --enable

2. Update the Codebase

Replace the existing Moodle core files with the new version. If using Git, this involves fetching the new branch. If using a ZIP archive, extract the files over the existing installation.

Critical: Do not overwrite config.php or the moodledata folder. These contain your site-specific configuration and uploaded files.

3. Execute the Database Upgrade

Run the upgrade script. The --non-interactive flag is used for automation, but removing it allows you to manually confirm plugin installations if prompted.

php admin/cli/upgrade.php --non-interactive

Risk: If the script terminates with a "Fatal Error," check the PHP error logs immediately. This is usually caused by a PHP version mismatch or an incompatible third-party plugin in the /local/ or /mod/ directories.

4. Finalize and Open the Site

Once the CLI reports that the upgrade is complete, disable maintenance mode:

php admin/cli/maintenance.php --disable

Verification and Health Checks

Success is not defined by the script finishing, but by the site functioning. Use these three checks to verify the installation:

Check Method	Command/Location	Expected Result
Environment Check	php admin/cli/healthcheck.php	No critical warnings regarding PHP extensions or DB settings.
System Notifications	Site admin > Notifications	All core components marked as "Up to date."
Cron Execution	php admin/cli/cron.php	Completion without "Error" or "Warning" logs.

Finally, perform a manual smoke test: log in as a student, upload a file to an assignment, and verify that course content renders correctly.

Recovery and Rollback

Because database migrations are irreversible, a "rollback" is a restoration process rather than an undo command.

1. Restore Database: Import the backup SQL dump created during the prerequisites phase.
2. Revert Code: Replace the new Moodle codebase with the previous version's files.
3. Restore Data: If moodledata was modified or corrupted, restore it from the backup.
4. Clear Cache: Run php admin/cli/purge_caches.php to remove any cached fragments from the failed upgrade version.