WordPress search replace for domain and content changes

What search-replace does

Search-replace walks the WordPress database and swaps every occurrence of an old string for a new one, column by column and table by table. It is the tool for moving a site from oldsite.example to newsite.example, rebranding a repeated phrase, or fixing a batch of stale URLs. It operates on the database, not the files, so media URLs living inside post content and options get rewritten together.

The database cleanup guide covers when a bulk table operation is warranted and the backup you need before it. This page is the layer underneath: how the replace itself works, and the serialized data problem that makes a naive method unsafe.

The serialized data problem

WordPress stores many settings and widget values as serialized PHP arrays. A serialized string records its own length: the value s:10:"wordpress" means a 10-character string. When you run search-replace, the length field has to be updated to match the new value, or the whole array corrupts.

The failure looks like this:

• Run a plain UPDATE (or a bad regex) changing "wordpress" to "wordpress-site".
• The stored array's length field still says s:10 for a now 13-character string.
• PHP reads the value, fatals, or returns garbage, and every option or widget that depended on the array breaks, often silently, until you notice the admin panel is weird.

The fix is a tool that recounts lengths. WP-CLI search-replace and the Search Replace DB plugin both do this correctly by default. That is the whole reason not to hand-edit the database tables directly.

Two methods, both safe

Method A, WP-CLI:

wp search-replace 'http://old.example' 'https://new.example' --all-tables

Add --dry-run first to count matches without writing, then run the real pass with --recurse-objects where an option stores URLs inside nested arrays.

Method B, Search Replace DB plugin:

1. Back up the database.
2. Install Search Replace DB, open it in the admin, paste old and new strings.
3. Run a Dry Run first to see the table and row counts.
4. Run the live replace, then remove the plugin (it should never stay installed).

Both methods share the same rules: use the longest unique strings you can, a bare "example" is riskier than https://old.example, and run the replace only after you have the exact before state recorded.

The two-step method

For a URL change, replacing the domain in one pass often leaves a duplicated result (old URI paths plus new domain paths mix). The two-step method cuts through it:

1. First replace the full old URL https://old.example with the placeholder https://STAGING.example, run a dry and live pass.
2. Then replace the unique placeholder https://STAGING.example with https://new.example.
3. Clear every cache, then search for the old URL again and confirm zero hits.

Using the placeholder prevents the tool from matching the middle of an already-replaced string and produces a cleaner result than trying to find "replace all URLs in one run" patterns.

Verify and commit

After the replace, load the homepage and a settings page, check the media library for mixed URLs, and confirm the site behaves while the old search shows nothing. If a page looks broken, restore the backup from before the change and run the replace again with a narrower string. Cache and CDN are the next suspects: stale HTML from an old staging to live flip can keep showing the old URL long after the database is clean.

Prevention

Always back up first, dry-run before every pass, keep the longest feasible search string, place-hold on a URL swap, and remove the GUI plugin, plus clear caches, after the operation. Search-replace is the single most useful correction tool in the WordPress kit, and the discipline around it is what keeps it useful instead of destructive.

When to involve a professional

If a broken option means the admin stops loading or a plugin settings screen shows corrupted data after a replace, stop editing table data and restore the backup or hand to a developer with the original strings and the tool used.