Skip to main content

wp core update-db

Overview

Apply any pending WordPress database schema upgrades after updating WordPress core files. This is the second step in a core update — files first, then database.

What It Does​

After wp core update downloads and installs new core files, some WordPress versions require database table schema changes. wp core update-db runs all pending dbDelta() upgrade routines, updates the db_version in wp_options, and reports what was changed.

Skipping this step can cause subtle bugs — undefined database columns, deprecated data structures, or admin notices like "Database update required."

Syntax​

wp core update-db [--network] [--dry-run]

Options & Flags​

FlagDescription
--networkRun update on all sites in a multisite network
--dry-runShow what would be updated without making changes

Basic Usage​

Run database update (standard)​

wp core update-db

Preview changes before applying​

wp core update-db --dry-run

Update all sites in a multisite network​

wp core update-db --network

Expected Output​

When changes are needed:

Success: WordPress database upgraded successfully from db version 56657 to 57155.

When already up to date:

Success: WordPress database already at latest db version 57155.

The Core Update Workflow​

Always run wp core update-db immediately after wp core update:

# Step 1: Update core files
wp core update

# Step 2: Update the database schema
wp core update-db

# Step 3: Verify (optional)
wp core verify-checksums
Don't skip wp core update-db

Running WordPress with outdated DB schema causes undefined behavior. Always run wp core update-db as part of your update workflow.

Real-World Scenarios​

Scenario 1: Standard maintenance update​

#!/bin/bash
echo "Starting WordPress maintenance update..."

# Backup first
wp db export backup_before_update_$(date +%Y%m%d).sql

# Enable maintenance mode
wp maintenance-mode activate

# Update core
wp core update

# Update database schema
wp core update-db

# Update plugins and themes
wp plugin update --all
wp theme update --all

# Disable maintenance mode
wp maintenance-mode deactivate

echo "Update complete: $(wp core version)"

Scenario 2: Multisite network database update​

# Update all sites in the network
wp core update-db --network

# Verify
wp site list --format=table

Scenario 3: Dry run before production update​

# Preview what will change
wp core update-db --dry-run

# If looks good, apply
wp core update-db

Scenario 4: CI/CD pipeline database step​

# After deploying new core files
wp core update-db --quiet && echo "DB schema up to date" || echo "DB update failed"

Best Practices​

  1. Always pair with wp core update — never skip the DB step.
  2. Take a DB backup first with wp db export before any update.
  3. Use --dry-run in production to preview changes before applying.
  4. Use --network on multisite — each sub-site may need its own DB upgrade.
  5. Use with maintenance mode on live sites to prevent data inconsistency during upgrade.

Troubleshooting​

ProblemCauseFix
Admin shows "Database update required" bannerupdate-db not run after core updateRun wp core update-db immediately
Command reports errorsCorrupt tables or missing columnsRun wp db repair then retry
Multisite: some sites not updatedSites skipped in --network runRun again or target specific sites with --url
Silent failurePermissions issueCheck MySQL user has ALTER TABLE privileges

Quick Reference​

wp core update-db                    # Apply pending schema upgrades
wp core update-db --dry-run          # Preview without applying
wp core update-db --network          # All sites in multisite
wp db export backup.sql              # Backup before updating

Next Steps​