MediaWiki Maintenance Best Practices

MediaWiki ships with roughly 200 maintenance scripts covering everything from database backups to search index rebuilding, and most of them are run from the command line rather than through any web interface. Unlike many other content management systems, MediaWiki does not provide a mature web-based interface for running these scripts in production, so administrators are expected to have shell access to the server and a basic comfort with the command line.

Maintenance in this context covers several distinct but related responsibilities: keeping the software itself up to date, backing up the database and uploaded files on a predictable schedule, running the background job queue so that deferred updates do not pile up, and periodically rebuilding caches and indexes so that search, recent changes, and link tables stay consistent with the actual content of the wiki. Neglecting any one of these does not usually cause an immediate failure - it causes a slow drift between what the wiki's tables say and what is actually true, which is often harder to diagnose later than a clean failure would have been.

This guide covers the maintenance scripts system, the job queue and how to schedule it, backup and restore procedures, the upgrade process, and the recurring tasks that keep a MediaWiki installation healthy over the long term.

For the initial server setup that maintenance work depends on, see "How to Install MediaWiki on Ubuntu Server".

How MediaWiki Maintenance Scripts Work

MediaWiki's maintenance scripts live in the maintenance/ directory of the installation root. As of MediaWiki 1.40, scripts should be invoked indirectly through a single entry point rather than called directly:

php maintenance/run.php <scriptName>

Invoking a script file directly (for example, php maintenance/update.php) still works on older versions but will trigger a deprecation warning on MediaWiki 1.40 and later. Running scripts requires either direct shell access to the server or shell access through an SSH client such as ssh on Linux/macOS or PuTTY on Windows. On shared hosting without shell access, a small number of extensions exist to run scripts via the web, though these are generally not considered mature enough for production use.

If a script needs to modify the structure of the database - as update.php does, for example - additional configuration variables may need to be set in LocalSettings.php to permit this. Most scripts accept a --help flag that lists their available options, and a --conf flag to point at a non-default LocalSettings.php file when managing more than one wiki on the same server.

A quick way to confirm a maintenance setup is working correctly is to run the built-in statistics script:

php maintenance/run.php showSiteStats

This returns a short summary of total edits, articles, pages, users, and images, which is a useful smoke test after any change to the server environment.

Step 1: Run update.php After Every Upgrade or Extension Install

During major version upgrades and after installing or updating certain extensions, MediaWiki frequently needs to change the structure of its own database - adding tables, adding fields, or changing data types and keys. In these cases, running the update script is mandatory, not optional.

php maintenance/run.php update --quick

When installing or updating an extension, check the "Database changes" field in the extension's infobox on its mediawiki.org page. If it says "Yes," running the update script afterward is necessary; if extensions are skipped, schema mismatches can surface later as obscure database errors rather than a clear message at install time.

Restoring an older database backup into a newer version of MediaWiki and then running the update script is supported. Restoring a newer backup into an older version of the software is not.

Step 2: Back Up the Database, Files, and Site Configuration

A full MediaWiki backup has three parts, and all three are necessary: the database, the uploaded files, and the site configuration. Treating any one of these as optional is the most common cause of an incomplete restore later.

Put the wiki in read-only mode before backing up. This ensures the backup is internally consistent, since a page edited mid-backup could otherwise end up only partially captured. Add the following to LocalSettings.php before starting the backup, and remove it afterward:

$wgReadOnly = 'Performing scheduled maintenance, access will be restored shortly';

Dump the database. The most critical data in a MediaWiki installation lives in the database, and the standard tool for dumping a MySQL or MariaDB-backed wiki is mysqldump:

mysqldump --default-character-set=binary -u wikidb_user -p wikidb > wikidb_backup.sql

Specifying the correct character set matters - using the wrong one can silently corrupt special characters in the dump. Compress the result for storage:

gzip wikidb_backup.sql

Create an XML dump in addition to the database dump. This is good practice even though it is not a substitute for the database backup, since it provides a portable copy of page content that can be imported into a different wiki or a different database engine entirely:

php maintenance/run.php dumpBackup --full --output=gzip:wikidump.xml.gz

An XML dump on its own is not a full backup. It does not include user accounts, image files, deleted revisions, or other site-related data, so it should always be paired with the database dump rather than used in place of it.

Back up the uploaded files. Copy the entire upload directory (images/ by default) to the backup location:

tar -czf images_backup.tar.gz /var/www/html/w/images

The images/thumb/ subdirectory, which stores generated thumbnails, can optionally be excluded to save space, since thumbnails are regenerated automatically as they are requested after a restore.

Back up the configuration and code. Copy LocalSettings.php and any custom skins or extensions that are not tracked elsewhere in version control. Unmodified, upstream MediaWiki core and extension code does not strictly need to be backed up, since it can be re-downloaded, but locally modified files and configuration cannot be recreated from anywhere else.

Lift read-only mode. Remove or comment out the $wgReadOnly line once all backup steps are complete.

Step 3: Schedule Backups and Verify Restores

A backup that has never been tested for restoration is, in practice, an assumption rather than a backup. It is recommended to practice the restore process on a test instance rather than wait until a real failure forces the first attempt.

To restore a database dump:

mysql -u wikidb_user -p wikidb < wikidb_backup.sql

To import an XML dump into a wiki (used for restoring content, or for migrating it elsewhere):

php maintenance/run.php importDump --quiet wikidump.xml

After importing an XML dump, run the recent changes rebuild so that Special:RecentChanges reflects the restored content:

php maintenance/run.php rebuildrecentchanges

Automate the backup schedule with cron rather than relying on it being run manually. A weekly database and file backup is a reasonable minimum for most wikis; busier wikis with frequent edits may warrant daily database dumps. Store backups off the server they were taken from - a backup that lives only on the same disk as the wiki it protects does not protect against hardware failure.

Step 4: Schedule the Job Queue

MediaWiki defers certain expensive operations - updating links after a template edit, sending email notifications, generating video thumbnails - to a job queue rather than performing them immediately during a page request. By default, one job is pulled from the queue and executed at the end of each web request, a behaviour controlled by $wgJobRunRate.

Running jobs inline on web requests works as a zero-configuration default, but it adds latency to page loads and does not scale well on a wiki with meaningful traffic or large template edits. The recommended approach for any wiki beyond the smallest installation is to disable inline job running and schedule the job queue separately via cron or a system service.

Disable inline job execution in LocalSettings.php:

$wgJobRunRate = 0;

Add a cron entry to run the job queue every hour:

0 * * * * /usr/bin/php /var/www/wiki/maintenance/run.php runJobs --maxtime=3600 > /var/log/runJobs.log 2>&1

The job runner should be executed as the same user the web server runs as, so that file permissions on uploaded files and other filesystem operations triggered by jobs are handled correctly. An hourly cron schedule is simple to set up but means template edits or notifications can take up to an hour to fully propagate; wikis that need faster propagation typically run runJobs.php in a continuous loop as a background service instead, guarding against overlapping runs with a lock file.

Note that the default memory limit for a single job is 150 MB, which exists specifically so that one malformed job cannot consume all of the server's available memory.

Step 5: Clear and Manage a Stuck Job Queue

Occasionally a job queue stalls - usually because one job has failed repeatedly or because a large batch of jobs (for example, from editing a widely-used template) has built up faster than they can be processed.

To manually delete jobs from the queue or return abandoned jobs to circulation, use:

php maintenance/run.php manageJobs

This script returns abandoned jobs to circulation but does not itself execute them - running runJobs.php afterward is still required to actually process them.

If the queue is severely stuck and a database administration tool such as phpMyAdmin is available, locate the job table directly. A single hung job will usually show a hash value in the job_token column; deleting that specific row can be enough to let the rest of the queue proceed. If that does not resolve the issue, clearing the entire job table is a last resort that discards all pending jobs.

Step 6: Rebuild Indexes and Caches After Bulk Changes

Several maintenance scripts exist specifically to rebuild derived data - search indexes, link tables, and recent changes - after bulk imports, extension changes, or data corruption. These tables are not the source of truth (the page content and revisions are), so rebuilding them is generally safe, if sometimes slow.

To rebuild everything at once - the full-text search index, recent changes, and page/category/image link tables:

php maintenance/run.php rebuildall

This is equivalent to running rebuildtextindex.php, then rebuildrecentchanges.php, then refreshLinks.php in sequence. It is appropriate to run after importing a moderate amount of data into the wiki, but for very large XML dumps it can take a long time because it has to parse every page, and it is not recommended as the import strategy for large data sets. Running it also marks all previously patrolled edits as unpatrolled, which is worth knowing before running it on a wiki that relies on patrol status.

rebuildall.php does not import or register image files even if they already exist in the upload directory and are referenced by articles. Use a dedicated import script for that:

php maintenance/run.php importImages --skip-dupes --extensions png,jpg --search-recursively "/path/to/images"

This bulk-imports files from a directory, placing them in the upload directory and creating File-namespace pages, as though each had been uploaded individually via Special:Upload.

After renaming pages in bulk, changing a heavily-transcluded template, or any operation that affects link relationships without going through normal bulk import, running just the link refresh is often sufficient and considerably faster than a full rebuild:

php maintenance/run.php refreshLinks

Step 7: Write and Run Custom Maintenance Scripts Safely

Sites with non-trivial customisation often need their own maintenance scripts - for example, to migrate data after a schema change introduced by a custom extension. MediaWiki provides an abstract Maintenance class specifically to make writing these straightforward, handling option parsing, output, and database connections so the script author does not have to.

If a custom script is designed to operate on a large number of items - potentially all pages or all revisions on the wiki - certain best practices matter considerably more than they would for a one-off task, since "all revisions" can mean billions of rows and months of runtime on a large site.

Process large item counts in batches rather than one query against the whole table. A batch size between 100 and 1,000 rows is typical, depending on how expensive each individual item is to process. Maintenance scripts also support a --profiler option that reports what percentage of execution time was spent in any given function, which is useful for diagnosing why a custom script is slower than expected. It is also recommended to write tests for custom maintenance scripts just as for any other class in the codebase, rather than treating them as exempt from the project's usual testing practices.

Step 8: Keep Version Control and the Filesystem Separated

A wiki's version control system (VCS) should contain code - MediaWiki core, extensions, and skins - and nothing else. It is not the right place for uploaded files, log files, or other runtime data, since these change constantly and have no meaningful "diff" history the way code does.

The recommended pattern is to put unmodified, upstream MediaWiki and extension code in its own branch, separate from any local modifications, so that pulling in upstream updates does not conflict with site-specific changes. Uploaded files belong in the backup rotation described above, not in the VCS history.

Configuration Reference

Key MediaWiki Maintenance Configuration Variables

Variable	Purpose	Default
$wgJobRunRate	Probability that a queued job runs at the end of a web request; set to 0 to run jobs only via cron/CLI	1
$wgReadOnly	When set to a string, puts the wiki into read-only mode and displays that string as the reason	Not set (wiki is writable)
$wgUpdateRowsPerJob	Number of rows processed per job for batched update operations	Varies by version
$wgRevisionCacheExpiry	How long old revisions are kept in the object cache; recommended to set to 0 before large dumps	Varies by version
$wgDBadminuser / $wgDBadminpassword	Optional separate database credentials used by maintenance scripts that need elevated schema permissions	Not set (uses standard DB credentials)

Best Practices

Run update.php after every core upgrade and after installing or updating any extension whose infobox indicates database changes - skipping this step is the single most common source of confusing post-upgrade errors. Put the wiki into read-only mode for the duration of a backup so the database and file backups are taken from a consistent state. Pair every XML dump with a full database dump rather than relying on the XML dump alone, since it does not capture user accounts, deleted revisions, or other site data. Schedule backups with cron rather than performing them manually, and store copies off the server being backed up. Disable inline job execution ($wgJobRunRate = 0;) and run the job queue from cron or a background service on any wiki with meaningful traffic, rather than letting jobs run inline on user-facing requests. Practice restoring a backup on a test instance before a real failure makes that the first attempt. Batch any custom maintenance script that touches a large number of pages or revisions, rather than operating on the full table in one pass. Keep uploaded files and log files out of version control, and keep locally modified code in a separate branch from unmodified upstream code.

Common Mistakes

Treating an XML dump as a complete backup is a frequent and serious mistake, since it silently omits user accounts, deleted revisions, and other data that only a full database dump preserves. Performing a backup without putting the wiki into read-only mode can produce a backup that is internally inconsistent if content changes mid-backup. Leaving $wgJobRunRate at its default of 1 on a busy wiki adds avoidable latency to every page request and is often the unexplained cause of a wiki that "feels slow" under load. Running a bulk maintenance script against an entire table of pages or revisions without batching can exhaust server memory or run for an unexpectedly long time on a large wiki. Forgetting to run update.php after an extension upgrade - and only discovering the missing schema change later, through an obscure database error rather than a clear message - is a common and avoidable failure mode. And restoring a database backup into an older version of MediaWiki than the one it was taken from is not supported and should not be attempted.

Troubleshooting Common Maintenance Issues

Common MediaWiki Maintenance Errors and Fixes

Symptom	Likely Cause	Fix
Deprecation warning when running a maintenance script directly	Script invoked as php maintenance/scriptName.php on MediaWiki 1.40+ instead of through the new entry point	Invoke via php maintenance/run.php scriptName instead
"Division by zero" warning from dumpBackup.php	The value passed after --report is zero or not a number	Run dumpBackup.php without the --report flag; it will print status every 100 pages by default
Template edit takes up to an hour to propagate to all pages	Job queue is only processed by an hourly cron job, and $wgJobRunRate is set to 0	Reduce the cron interval, or run runJobs.php in a continuous loop as a background service instead
Job queue appears stuck or hung	A single failed job is blocking the queue, or jobs are accumulating faster than they are processed	Use manageJobs.php to return abandoned jobs to circulation, or locate and remove the specific hung row in the job database table
Page links, categories, or search results are out of date after a bulk import	Link and search index tables were not rebuilt after the import	Run rebuildall.php, or just refreshLinks.php if only link tables are affected
Images already present in the upload directory don't show up as wiki files	rebuildall.php does not register image files on its own	Run importImages.php to register existing files in the upload directory
Restoring a backup fails or produces inconsistent data	Attempting to restore a newer database backup into an older version of MediaWiki	Restore into an equal or newer MediaWiki version, then run update.php

Frequently Asked Questions

How often should I back up a MediaWiki installation?

At minimum, weekly database and file backups are recommended for most wikis, with more frequent backups for wikis with heavy edit activity. Regardless of frequency, backups should be automated with cron rather than performed manually, and should be tested by performing an actual restore periodically rather than assumed to work.

Is an XML dump enough to fully back up my wiki?

No. An XML dump created by dumpBackup.php contains page content and revision history but explicitly does not include user accounts, image files, or deleted revisions. A full database dump via mysqldump, alongside a separate backup of the upload directory, is required for a complete backup.

Do I need to run update.php after every extension update?

Only if the extension's database schema has changed, which is indicated on the extension's mediawiki.org page under "Database changes." If that field says "Yes," running update.php afterward is necessary; if it says "No," it generally is not, though running it anyway is harmless.

Should jobs run on every web request or via cron?

For a small, low-traffic wiki, the default of running one job per web request ($wgJobRunRate = 1) is a reasonable zero-configuration choice. For any wiki with meaningful traffic, disabling inline job running and scheduling runJobs.php via cron or a background service is the recommended approach, since it removes job-processing latency from user-facing page loads.

What's the difference between rebuildall.php and refreshLinks.php?

rebuildall.php is the broader operation: it rebuilds the full-text search index, recent changes, and all link tables in one pass, and is appropriate after a significant bulk import. refreshLinks.php only rebuilds the link tables, and is faster when that is the only thing that needs correcting - for example, after editing a heavily-transcluded template.

Can I run maintenance scripts without shell access to the server?

Generally no, in any reliable way. MediaWiki's maintenance scripts are designed to be run from the command line, and while a small number of extensions attempt to provide web-based access for shared hosting environments without shell access, these are not considered mature enough for production use.

Conclusion

MediaWiki's approach to maintenance is deliberately command-line-first and script-driven: the software trusts an administrator with shell access to run the right script at the right time, rather than wrapping every operation in a web UI. That trust comes with responsibility - backups, schema updates, and job queue scheduling all need to be set up deliberately rather than assumed to happen automatically.

The steps in this guide follow a practical order: confirm the maintenance script entry point and update process first, establish a reliable backup routine, schedule the job queue so it does not slow down user-facing requests, and know which rebuild scripts to reach for after bulk changes. None of these are difficult individually, but skipping any one of them tends to surface later as a problem that is harder to diagnose than it would have been to prevent.

For help setting up scheduled maintenance, backup automation, or reviewing the health of an existing installation, see SolidWiki's MediaWiki Development Services page.

See Also

• MediaWiki Security Hardening Guide
• MediaWiki File Upload Management Guide
• How to Install MediaWiki on Ubuntu Server
• MediaWiki Performance Optimisation
• MediaWiki Namespaces Explained

External Links

• MediaWiki Manual: Maintenance Scripts
• MediaWiki Manual: Backing Up a Wiki
• MediaWiki Manual: Restoring a Wiki from Backup
• MediaWiki Manual: Job Queue
• MediaWiki Manual: Writing Maintenance Scripts