Maintenance May 7, 2026

WordPress Database Upgrade: When, Why and How to Run It Safely

After a core update the database schema must be upgraded too. Here is how to run upgrade.php or wp core update-db safely, with a backup and a check.

When WordPress upgrades to a new version, the table structure itself sometimes changes - new columns, new indexes, additional tables. The files are updated as soon as the download completes, but the database needs an extra step that does not happen automatically. Until that step runs, the site is in a half-updated state: new code against an old schema.

Why this matters

WordPress stores a key called db_version in wp_options - a number representing the schema the database was last upgraded to. The core files contain a constant $wp_db_version representing the schema the code needs. When the two disagree, WordPress shows every admin who visits /wp-admin/ a "Database Update Required" screen until they click "Update WordPress Database". During this window: internal APIs that rely on new structures fail, plugins using dbDelta() may write into the wrong schema, and certain queries return "Unknown column" errors. On a multisite installation with many sub-sites, the half-updated state can persist for days if no admin logs into each sub-site.

How to detect

The most obvious sign: the "Database Update Required" screen on accessing wp-admin. Manually, compare $wp_db_version in wp-includes/version.php to the value in wp_options:

wp option get db_version
grep wp_db_version wp-includes/version.php

If they differ, an upgrade is needed. RankPlus reads both through the REST API and flags the gap.

How to fix

  1. Back up the database first. This step alters the schema and is not automatically reversible. Use UpdraftPlus, wp db export pre-upgrade.sql, or mysqldump over SSH.
  2. The recommended path: WP-CLI - fast, accurate and especially good for multisite: wp core update-db. For multisite add --network: wp core update-db --network.
  3. Browser alternative: visit https://YOUR-SITE/wp-admin/upgrade.php and click "Update WordPress Database". This runs upgrade_all().
  4. On a site with hundreds of thousands of rows the process may take several minutes. Do not interrupt it.
  5. If it fails halfway through: enable WP_DEBUG and WP_DEBUG_LOG in wp-config.php, retry, and check debug.log. The error will name a specific table or a plugin that interferes.
  6. If the error is "Could not perform query" the MySQL user may lack ALTER privileges. Ask the host to grant them.

Common mistakes

  • Upgrading without a backup: if something fails mid ALTER TABLE you can be left with a partially corrupt table. A backup is not optional.
  • Closing the browser mid-run: the operation continues server-side, but interrupting the request can leave an unfinished ALTER. WP-CLI handles this far more gracefully.
  • Multisite with many sub-sites: without --network, only the main site is upgraded and sub-sites remain stuck.
  • DB in read-only mode: some hosts lock the database for writes after exceeding a quota. Request unlock before the upgrade.

Verifying the fix

Run wp option get db_version again and compare to $wp_db_version - they must match. Visit /wp-admin/ - the upgrade screen should not appear. Open the home page and a random post and confirm the page loads without "Unknown column" entries in the log. In RankPlus the status returns to green on the next scan.

Tip: If you manage many sites, append wp core update-db to the script that runs wp core update. That way you never miss the schema-upgrade step.
More in this category ← Back to all docs