MediaWiki Upgrading — Version Compatibility, Upgrade Procedure, Testing, and Rollback

In this tutorial, you will learn about MediaWiki Upgrading. We cover key concepts, practical examples, and best practices to help you master this topic.

Upgrading MediaWiki requires careful planning — checking version compatibility, backing up everything, following the upgrade procedure in order, testing on a staging environment, and preparing a rollback plan — the same Process Wikipedia uses for its production rollout to millions of users.

What You'll Learn

• Checking version compatibility
• Preparing for an upgrade
• Executing the upgrade procedure
• Testing after upgrade
• Handling extension compatibility
• Rolling back if something goes wrong
• Upgrading in a wiki farm

Why It Matters

Running an outdated MediaWiki is a security risk. Each release includes security fixes, bug patches, and new features. But upgrading carelessly can break your wiki. Extensions may be incompatible. The database schema may change. A failed upgrade can leave your wiki unusable. A proper upgrade process minimizes risk and ensures a smooth transition.

Real-World Use

A DodaTech wiki runs MediaWiki 1.40. Version 1.42 is released with important security fixes and new VisualEditor features. The administrator checks the release notes, tests the upgrade on a staging wiki, backs up the production database, runs the upgrade on a maintenance window, and verifies everything works. Total downtime: 15 minutes. No issues.

Learning Path

flowchart LR
  A["37: Backup & Restore"] --> B["38: Performance Tuning"]
  B --> C["39: Upgrading MediaWiki"]
  C:::current
  D["40: Security"]
  C --> D

  classDef current fill#38bdf8,color#0f172a,stroke-width:2px

Step 1: Check Version Compatibility

Current Version

Check your current MediaWiki version:

Special:Version on your wiki

Or from the command line:

grep 'MW_VERSION' includes/VersionConstants.php

Target Version

Choose a target version. MediaWiki supports direct upgrades from the previous major version. If you are several versions behind, upgrade incrementally:

1.35 → 1.39 → 1.42

Do not skip major versions. Each major version has database schema changes that must be applied in order.

Release Types

• Long-Term Support (LTS): Supported for 3 years. Safe for production.
• Regular release: Supported for 1 year. Newer features but shorter support window.

Checking Extension Compatibility

Go to each extension's mediawiki.org page and check the supported versions. Create a compatibility matrix:

Extension          | Current Version | Compatible With
───────────────────|─────────────────|────────────────
VisualEditor       | 1.40            | 1.39, 1.40, 1.41, 1.42
Cite               | 1.40            | 1.39+
Scribunto          | 1.40            | 1.39+
Semantic MediaWiki | 4.2             | 1.39, 1.40, 1.41

Step 2: Prepare for Upgrade

Backup Everything

#!/bin/bash
# Pre-upgrade backup

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/pre-upgrade-$DATE"

mkdir -p $BACKUP_DIR

# Database
mysqldump --user=wiki_user --password=secure_password \
    --databases dodatech_wiki \
    | gzip > $BACKUP_DIR/database.sql.gz

# Files
tar -czf $BACKUP_DIR/images.tar.gz /var/www/mediawiki/images/
tar -czf $BACKUP_DIR/config.tar.gz /var/www/mediawiki/LocalSettings.php

# Code
tar -czf $BACKUP_DIR/code.tar.gz /var/www/mediawiki/

echo "Pre-upgrade backup complete: $BACKUP_DIR"

Read the Release Notes

MediaWiki release notes are in the RELEASE-NOTES-1.42 file after downloading:

# Key information to look for
grep -i "breaking" RELEASE-NOTES-1.42
grep -i "deprecated" RELEASE-NOTES-1.42
grep -i "removed" RELEASE-NOTES-1.42
grep -i "configuration" RELEASE-NOTES-1.42

Test on Staging

Always test the upgrade on a staging environment first:

1. Copy production database to staging
2. Copy production files to staging
3. Run the upgrade on staging
4. Test all features
5. Document any issues

Step 3: Execute the Upgrade

Dowload the New Version

# Get the latest MediaWiki
wget https://releases.wikimedia.org/mediawiki/1.42/mediawiki-1.42.0.tar.gz
tar -xzf mediawiki-1.42.0.tar.gz

Upgrade the Code

Option A: Replace in-place

# Put wiki in maintenance mode
echo '$wgReadOnly = "Upgrading to MediaWiki 1.42";' >> LocalSettings.php

# Backup old files
cp -r mediawiki mediawiki-old

# Extract new version
tar -xzf mediawiki-1.42.0.tar.gz -C /tmp/

# Copy new files (excluding config and images)
rsync -av --delete \
    --exclude 'LocalSettings.php' \
    --exclude 'images/' \
    --exclude 'extensions/' \
    --exclude 'skins/' \
    /tmp/mediawiki-1.42.0/ /var/www/mediawiki/

# Update extensions and skins
# (copy compatible versions)

Option B: Parallel directory

# Create new directory
mkdir /var/www/mediawiki-1.42
tar -xzf mediawiki-1.42.0.tar.gz -C /var/www/mediawiki-1.42

# Copy configuration
cp /var/www/mediawiki/LocalSettings.php /var/www/mediawiki-1.42/
cp -r /var/www/mediawiki/images /var/www/mediawiki-1.42/
cp -r /var/www/mediawiki/extensions /var/www/mediawiki-1.42/
cp -r /var/www/mediawiki/skins /var/www/mediawiki-1.42/

# Switch web server to new directory
# (update DocumentRoot in Apache/Nginx)

Run the Upgrade Script

cd /var/www/mediawiki
php maintenance/update.php

The script shows progress:

...mediawiki database upgrade...
...setting up logging table...done.
...setting up categorylinks table...done.
...setting up templatelinks table...done.
...done.

Requirements Check

If the upgrade script fails due to missing requirements:

# Check PHP version
php maintenance/checkRequirements.php

# Common issues:
# - PHP version too old (need 8.1+ for 1.42)
# - Missing PHP extensions (mbstring, xml, intl)

Step 4: Post-Upgrade Tasks

Run All Maintenance Scripts

php maintenance/update.php          -- Already done above
php maintenance/refreshLinks.php
php maintenance/rebuildrecentchanges.php
php maintenance/rebuildall.php

Clear Caches

php maintenance/rebuildall.php --cache
rm -rf cache/filecache/*

Verify Special:Version

Go to Special:Version and check:

• MediaWiki version is correct
• All extensions show compatible versions
• No "Unknown version" entries

Test Core Features

• View a page
• Edit a page
• Upload a file
• Search for content
• Create a new page
• View RecentChanges

Step 5: Handle Extension Issues

Disable Problematic Extensions

If an extension causes errors:

// Comment out the extension in LocalSettings.php
// wfLoadExtension( 'ProblemExtension' );

Then:

1. Check if a compatible version exists
2. Download the updated version
3. Test on staging
4. Enable on production

Extension Compatibility Check

# Check all extensions at once
php maintenance/checkComposer.php

Step 6: Rollback

If the upgrade fails or causes critical issues, rollback immediately:

# 1. Restore database
mysql --user=wiki_user --password=secure_password \
    dodatech_wiki < backup/database.sql

# 2. Restore files
tar -xzf backup/code.tar.gz -C /
tar -xzf backup/images.tar.gz -C /

# 3. Restore config
tar -xzf backup/config.tar.gz -C /

# 4. Reboot web server
systemctl restart apache2

# 5. Verify rollback
# Check Special:Version shows old version
# Verify pages load correctly

Step 7: Upgrade in a Wiki Farm

For wiki farms, upgrade each wiki individually:

for config in /var/www/mediawiki/config/*.php; do
    echo "Upgrading: $config"
    php maintenance/update.php --conf=$config
    php maintenance/refreshLinks.php --conf=$config
done

Upgrade Checklist

Pre-Upgrade:
  ☐ Read release notes and check for breaking changes
  ☐ Check extension compatibility matrix
  ☐ Back up database, files, and code
  ☐ Test upgrade on staging environment
  ☐ Schedule maintenance window

During Upgrade:
  ☐ Put wiki in read-only mode
  ☐ Replace code with new version
  ☐ Run update.php
  ☐ Run post-upgrade maintenance scripts

Post-Upgrade:
  ☐ Clear all caches
  ☐ Verify Special:Version
  ☐ Test core features
  ☐ Check all extensions
  ☐ Monitor error logs
  ☐ Remove read-only flag

Rollback:
  ☐ Restore database from backup
  ☐ Restore code from backup
  ☐ Verify rollback success

What You Learned

• Check version compatibility before upgrading
• Always back up before upgrading
• Upgrade the code, then run update.php
• Post-upgrade tasks include rebuilding links and clearing cache
• Test extensions individually if issues arise
• Rollback restores from backup when needed
• Wiki farm upgrades iterate over each wiki's configuration

In the next lesson, you'll learn about security hardening.

Common Mistakes

Practice Questions

1. What three pre-upgrade steps are essential before upgrading MediaWiki?
2. Why should you not skip major versions when upgrading?
3. What is the rollback procedure if an upgrade fails?
4. Challenge: Perform a simulated upgrade. Create a backup of your current wiki (database, files, code). Set up a staging environment (separate directory and database) that mirrors production. "Upgrade" the staging environment to the latest MediaWiki version. Document every step in a runbook. If any extension is incompatible, find the compatible version or disable it. Test all features on staging. Create a rollback script that restores from backup. Finally, create a procedure document that another administrator can follow to perform the upgrade.

FAQ

Mini Project

Goal: Create a complete upgrade runbook.

1. Document your current MediaWiki version and all installed extensions
2. Create a compatibility matrix showing each extension's version compatibility with the target MediaWiki version
3. Write a pre-upgrade backup script
4. Set up a staging environment mirroring production
5. Practice the upgrade on staging:
   • Download the new version
   • Replace the code
   • Run update.php
   • Run post-upgrade scripts
   • Test all features
6. Document any issues encountered and their solutions
7. Write the rollback procedure
8. Create a maintenance window checklist
9. Share the runbook with other administrators

What's Next

You now know how to keep your wiki updated. The final lesson covers security — protecting your wiki from threats.

Continue to Lesson 40: Security — learn about hardening, .htaccess, CSP, XSS prevention, and CAPTCHA configuration.