WordPress Database Migration: A Step-by-Step Guide for Developers

A safe WordPress database migration starts with a verified backup, a clean staging test, and a controlled search-and-replace process. Developers should treat the database as the source of truth for content, settings, users, orders, and plugin data. One missed serialized value or hardcoded URL can break widgets, menus, media paths, and checkout flows.

TLDR: A developer should export the source database, test the import on staging, replace URLs with a serialization-safe tool, then validate the site before switching traffic. For example, a WooCommerce store with 12,000 orders might cut downtime from 45 minutes to under 10 minutes by rehearsing the migration first. The safest path is backup, export, import, search and replace, config update, cache clear, and QA. The process is boring, but boring is good when production data is involved.

Contents

Why WordPress Database Migration Needs Care

WordPress stores more than posts and pages in its database. It stores plugin options, theme settings, user roles, menu items, shortcodes, product data, and internal URLs. That means a migration is not just a file transfer.

The catch is that WordPress also stores serialized PHP arrays. A normal text editor can damage them by changing string lengths without updating the serialized count. That tiny mistake can turn a working site into a white screen with no useful clue.

Step 1: Audit the Source Site

Before touching the database, the developer should document the current setup. This reduces guesswork during recovery.

WordPress version: Core version, multisite status, and language settings.
PHP and MySQL versions: The target server should support the same or newer compatible versions.
Table prefix: Usually wp_, but many sites use custom prefixes.
Database size: Large logs, sessions, and post revisions can slow exports.
Critical plugins: WooCommerce, membership tools, LMS plugins, and multilingual plugins need extra checks.

For busy sites, the developer should also check write activity. A news site or store may keep changing during migration. New posts, orders, or signups can be lost if the final sync is poorly timed.

Step 2: Create a Full Backup

A database backup alone is not enough. The developer should also back up the file system, especially the wp-content directory. Media files, custom plugins, themes, and uploads must match the migrated database.

Reliable backup options include:

phpMyAdmin export for smaller databases.
WP CLI for faster command-line exports.
mysqldump for large databases and scripted workflows.
Hosting snapshots as an extra rollback layer.

A common WP CLI export command is:

wp db export backup.sql

For larger databases, mysqldump gives more control:

mysqldump -u dbuser -p dbname > backup.sql

After export, the developer should check the file size and run a quick integrity check. A zero-byte SQL file is not a backup. Honestly, it feels like backup screens report “success” a little too often when the export failed 30 seconds earlier.

Step 3: Prepare the Target Environment

The target server should have a fresh database, matching credentials, and enough memory for import. The developer should create the database user with the right privileges, then update wp-config.php.

define('DB_NAME', 'new_database');
define('DB_USER', 'new_user');
define('DB_PASSWORD', 'strong_password');
define('DB_HOST', 'localhost');

If the migration includes a domain change, the developer should keep DNS untouched until the staging version passes checks. This avoids public errors and half-migrated sessions.

Step 4: Export and Import the Database

For a standard migration, the developer exports from the source and imports into the target. On small sites, phpMyAdmin is acceptable. On larger sites, command-line tools are safer and faster.

mysql -u new_user -p new_database < backup.sql

If import fails, the cause is often packet size, timeout limits, or character set mismatch. The developer may need to raise max_allowed_packet or split the SQL file. It drives developers crazy that a 600 MB import can fail after several minutes with one vague line about server disappearance.

Step 5: Replace URLs Safely

When moving from staging to production, or from one domain to another, URLs must be replaced safely. The developer should avoid raw SQL replacements for WordPress content that may include serialized values.

Best options include:

WP CLI search-replace: Fast and serialization-safe.
Interconnect IT Search Replace DB: Useful when WP CLI is unavailable.
Trusted migration plugins: Helpful for teams without shell access.

Example WP CLI command:

wp search-replace 'https://oldsite.com' 'https://newsite.com' --skip-columns=guid

The guid column is often skipped because it is an identifier, not a display URL. Changing it can create feed and tracking issues.

Step 6: Update Configuration and Permalinks

After import and URL replacement, the developer should confirm site URLs in the database and configuration. If WP_HOME and WP_SITEURL are defined in wp-config.php, they override database values.

define('WP_HOME', 'https://newsite.com');
define('WP_SITEURL', 'https://newsite.com');

Next, permalinks should be flushed. This can be done from the WordPress admin by saving the permalink settings, or by using WP CLI:

wp rewrite flush

Step 7: Clear Caches and Regenerate Assets

Database changes may not appear until caches are cleared. The developer should clear all cache layers:

WordPress cache plugins.
Object cache, such as Redis or Memcached.
Server cache from Nginx, LiteSpeed, or hosting tools.
CDN cache.
Browser cache during testing.

Some page builders and optimization plugins also store generated CSS in the database or uploads folder. The developer should regenerate those assets after the move.

Step 8: Run Quality Checks

A migration is not complete when the homepage loads. The developer should test the parts that make money or collect data.

Login and user roles: Admin, editor, customer, and member access.
Forms: Contact forms, lead forms, and newsletter signups.
Checkout: Cart, payment, tax, shipping, and order emails.
Search: Native search and external search tools.
Media: Images, PDFs, downloads, and private files.
SEO: Canonicals, redirects, sitemaps, and robots settings.

Step 9: Plan the Final Cutover

For low-traffic sites, the developer can schedule a quiet window and switch DNS. For high-traffic sites, the better method is a final database sync after putting the source site into maintenance mode.

A sample cutover plan may look like this:

Announce a short maintenance window.
Disable new orders, comments, or registrations.
Export the latest database.
Import into the target server.
Run search and replace.
Clear cache.
Run checkout and login tests.
Point DNS or update the load balancer.

DNS TTL should be lowered ahead of time, often to 300 seconds. This helps the new server receive traffic sooner.

Common Migration Problems

White screen: Often caused by PHP errors, plugin conflicts, or damaged serialized data.
Redirect loops: Usually caused by mixed HTTP and HTTPS settings.
Missing images: Often a file migration issue, not a database issue.
Broken layouts: Cached CSS or page builder assets may need regeneration.
Login failures: Cookie domain, SSL, or security plugin settings may be wrong.

FAQ

What is the safest way to migrate a WordPress database?

The safest method is to create a full backup, test the migration on staging, use a serialization-safe search-and-replace tool, then perform a controlled final sync.