Developer · Guide
How to Search and Replace in the WordPress Database Safely

Short answer
To search and replace in the WordPress database safely, back up the database first, then run WP-CLI search-replace with a dry run to preview the changes. Use the --skip-columns=guid flag so the post identifiers stay untouched, and check the counts before you run the real replacement. If you have no SSH access, Better Search Replace does the same job from the dashboard.
Key takeaways
- A plain SQL REPLACE breaks serialized data, because WordPress stores string lengths inside those values.
- WP-CLI search-replace handles serialized data, leaves primary keys alone, and skips tables with no primary key.
- Always run --dry-run first and read the counts before you write any change to the database.
- Never change the guid column in wp_posts, because feed readers use it to spot posts they already showed.
- Better Search Replace 1.4.11 needs WordPress 6.2 or later and PHP 8.1 or later, as of November 2026.
Why is a plain find and replace risky in WordPress?
A plain find and replace can break stored settings because WordPress saves some values as PHP serialized data that records each string length.
WordPress stores theme settings, widget data, and many plugin options as serialized arrays in a single database field. Developer.WordPress.org states that the WP-CLI search-replace command handles PHP serialized data, which is why a plain SQL REPLACE is not safe on its own (checked November 2026).
The WordPress documentation on moving a site warns that a search and replace on the whole database can cause issues with data serialization, because some themes and widgets store values with the URL length marked. WordPress.org gives that warning in its Migrating WordPress page (checked November 2026).
When the length number no longer matches the string, PHP cannot read the value back, so the setting comes back empty. A widget can vanish from a sidebar, a theme option can reset, and a page builder layout can lose its content, all without an error message.
That is why the safe route is a tool that reads each serialized value, replaces the text inside it, and writes it back with the length fixed. WP-CLI and Better Search Replace both do that work for you.
| Method | Needs | Handles serialized data | Best for |
|---|---|---|---|
| WP-CLI search-replace | SSH access | Yes | Domain moves and large sites |
| Better Search Replace | Dashboard access | Yes | Sites without SSH access |
| phpMyAdmin SQL REPLACE | Hosting control panel | No | Single plain-text values only |
| Search Replace DB script | FTP and a browser | Yes | Experienced admins without WP-CLI |
What do you need before you start?
You need a database backup, access to the server or dashboard, and the exact old and new strings before you change a single row.
Write down the exact strings first. For a domain move, the old string is the full old address with its scheme, such as https://old-domain.com, and the new string is the full new address, such as https://new-domain.com.
Decide which method fits your access. WP-CLI needs SSH access to the server, while Better Search Replace runs from the WordPress dashboard and needs no server tools. WordPress.org states that Better Search Replace has no server requirements aside from a running WordPress install (checked November 2026).
Check the PHP and database versions your site runs. WordPress.org recommends PHP 8.3 or greater, and MariaDB 10.11 or greater or MySQL 8.4 or greater, while older setups still run on PHP 7.4 and MySQL 5.5.5 (checked November 2026).
A guide on how to move a WordPress site without losing SEO covers the wider move around the database change, including redirects and checks after the switch.
How do you back up the database first?
Take a full database backup and keep a copy off the server before you run any replacement, because search and replace has no undo.
From the command line, export the database with WP-CLI from the WordPress folder. The command reads the database details from wp-config.php, so you do not type the password by hand.
wp db export ~/backups/before-search-replace.sql --add-drop-table
The --add-drop-table flag adds DROP TABLE lines to the export, so an import replaces the old tables instead of failing on tables that already exist.
From the dashboard, export the database with your backup plugin or from phpMyAdmin, and download the file to your own computer. A backup that stays on the same server is no help if the server itself fails.
A guide on how to back up a WordPress database walks through the export options step by step.
A guide on how to back up WordPress without a plugin covers the manual route with phpMyAdmin and the command line.
How do you search and replace with WP-CLI?
Run WP-CLI search-replace from the WordPress folder, with a dry run first, then the real run once the counts look right.
Start with the dry run. It runs the whole pass and reports what would change, without saving anything to the database.
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --all-tables-with-prefix --skip-columns=guid --dry-run
When the dry run looks right, run the same command without --dry-run to write the changes.
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --all-tables-with-prefix --skip-columns=guid
Developer.WordPress.org states that the command searches the tables registered to the $wpdb object by default, handles PHP serialized data, and does not change primary key values (checked November 2026).
| Flag | What it does | When to use it |
|---|---|---|
| --dry-run | Shows what would change without saving | Before every real run |
| --skip-columns=guid | Leaves the guid column untouched | Every domain replacement |
| --all-tables-with-prefix | Covers plugin tables that share your prefix | When plugins store the old URL |
| --all-tables | Covers every table, whatever its prefix | When the database holds other apps |
| --network | Covers every site in a multisite network | Multisite domain moves |
| --precise | Forces PHP handling for every column | Nested serialized data |
| --regex | Matches with a regular expression | Pattern replacements |
| --export=file.sql | Writes the changed data to a file | Preparing a dump for another server |
Developer.WordPress.org states that the --regex flag makes the run about 15 to 20 times slower, so use it only when a plain string match cannot do the job (checked November 2026).
Tables without a primary key are skipped by the command. Developer.WordPress.org states that you can check a table with wp db query 'DESCRIBE table-name' and look for PRI in the Key column (checked November 2026).
How do you read a dry run report?
Read the dry run table row by row and check that the counts match what you expect before you run the real replacement.
The report lists one row per table and column, with the number of replacements and the type of change. A row marked PHP means the column held serialized data that WP-CLI handled in PHP, while a row marked SQL means a plain string replacement was enough.
Check the biggest counts first. The wp_posts and wp_postmeta tables usually hold the most matches, because post content, image URLs, and page builder data live there.
A count of zero in a table you expected to change is a warning sign. It can mean the old string is spelled differently there, for example with a trailing slash or a www prefix, or that the table uses a prefix the command did not cover.
If the counts look wrong, fix the search string and run the dry run again. A dry run costs nothing, while a wrong real run costs a restore from backup.
How do you search and replace with Better Search Replace?
Install Better Search Replace, open Tools, then Better Search Replace, and run a dry run before you apply the change.
Install it from Plugins, then Add New, and search for “Better Search Replace”. WordPress.org states that once activated, the plugin adds a page under the Tools menu in the dashboard (checked November 2026).
On the plugin page, type the old string in the Search for field and the new string in the Replace with field. Select the tables to change, or leave all tables selected, and tick the dry run option first.
Run the dry run and read the count of fields that would change. If the count looks right, untick the dry run option and run the replacement for real.
WordPress.org states that the plugin supports serialization for all tables, lets you select specific tables, and works on multisite networks (checked November 2026).
Version 1.4.11, released 29 June 2026, requires WordPress 6.2 or later and PHP 8.1 or later. WordPress.org lists those requirements on the plugin page, and the plugin holds a 4.3 out of 5 rating from 546 reviews as of November 2026 (checked November 2026).
The plugin code is open source and lives in a public repo. GitHub hosts the Better Search Replace source code, which you can read before you install it (checked November 2026).
How do you search and replace with phpMyAdmin?
Use phpMyAdmin only for plain text in single columns, and never run a raw REPLACE across the whole database, because it breaks serialized data.
Open phpMyAdmin from your hosting control panel and select the WordPress database from the list on the left. Click the SQL tab at the top, type your query, and click Go to run it. Liquid Web describes those steps in its phpMyAdmin guide (checked November 2026).
A safe query targets one column in one table, such as the post content column:
UPDATE wp_posts SET post_content = REPLACE(post_content, 'https://old-domain.com', 'https://new-domain.com');
This query is safe only for post_content, which holds plain text and links. Never run the same REPLACE on wp_options or wp_postmeta, where serialized values live, because the length numbers will no longer match.
Check the number of rows the query reports as changed. If the count is far higher or lower than you expected, stop and check the backup before you run more queries.
What should you never change in the database?
Never change the guid column in wp_posts, and never edit serialized values by hand.
The guid column looks like a URL, but WordPress uses it as a permanent identifier for each post. WordPress.org states that the guid must never change, even when the domain changes, and warns never to change the contents of the guid column under any circumstances (checked November 2026).
Feed readers use the guid to know which posts they have already shown. Changing it makes every old post look new, so readers see the whole archive again as fresh content.
That is why the WP-CLI examples in the WordPress docs add --skip-columns=guid to every domain replacement. WordPress.org shows wp search-replace 'example.dev' 'example.com' --skip-columns=guid in its own examples (checked November 2026).
Never edit a serialized value by hand in phpMyAdmin either. Changing one character inside a serialized string breaks the length count, and PHP then drops the whole value.
How do you handle a multisite network?
Use the --network flag with WP-CLI, and check the network tables that hold each subsite domain.
By default, WP-CLI search-replace covers only the tables for the current site on a multisite install. Developer.WordPress.org states that on multisite, the command covers just the current site unless --network is specified (checked November 2026).
Add --network to cover all the tables registered to $wpdb across the network. The docs give this example for turning a production multisite database into a local one:
wp search-replace --url=example.com example.com example.test 'wp_*options' wp_blogs wp_site --network
The wp_blogs and wp_site tables hold the subsite domains, so include them when the domain itself changes. Check each subsite dashboard after the run, because subsite tables use their own prefixes such as wp_2_posts.
Better Search Replace also supports multisite. WordPress.org states that subsite admins can only change tables that belong to their own subsite (checked November 2026).
How do you check that the replacement worked?
Search the database for the old string after the run, then open the site and check the pages that held the most links.
Run a database search for the old address to catch leftovers. Developer.WordPress.org documents the wp db search command, which reports matches per table and column (checked November 2026).
wp db search 'old-domain.com'
Then open the home page, a post with images, and a page built with your page builder. Check that images load, links point to the new address, and widgets still show their content.
Open Settings, then General, and check that the WordPress Address and Site Address show the new domain. WordPress.org states that both settings should include the https:// part and no slash at the end (checked November 2026).
A guide on how to fix broken links after migration covers what to do when the search turns up links the replacement missed.
Flush the cache after the check. Clear any page cache and object cache, then load the site again, because a cached page can still show the old address after the database is fixed.
What mistakes should you avoid?
Avoid a missing backup, a search string that is too short, and a run without a dry run first.
A search string of old-domain.com with no scheme also matches email addresses and subdomains that contain it. Use the full address with https:// so the replacement only touches real URLs.
Skipping the dry run is the most common mistake. The dry run shows the counts before anything changes, and it is the only cheap way to catch a wrong string.
Running a raw SQL REPLACE on wp_options or wp_postmeta breaks serialized settings. Use WP-CLI or Better Search Replace for those tables, and keep phpMyAdmin for single plain-text columns.
Forgetting the cache leaves the site looking broken after a good replacement. Flush the cache and check the site in a fresh browser session.
A guide on how to optimize the WordPress database covers the cleanup steps that pair well with a search and replace, such as clearing old revisions and transients.
Frequently asked questions
Can I search and replace directly in phpMyAdmin?
Only for plain text in a single column, such as post_content. A raw REPLACE on wp_options or wp_postmeta breaks serialized values, because the stored length numbers no longer match. Use WP-CLI or Better Search Replace for those tables instead.
Why do I need a backup before a search and replace?
A replacement writes to thousands of rows at once and has no undo. If the search string is wrong, the only fast way back is to import the backup you took before the run.
What does --dry-run actually do?
It runs the full search and replace pass and prints a table of the changes it would make, without saving anything. You read the counts per table and column, fix the search string if they look wrong, then run the command again without the flag.
How long does a search and replace take?
Most small sites finish in seconds with WP-CLI, because it uses fast SQL queries where it can. The --regex flag slows the run to about 15 to 20 times longer, and --precise is slower too, so use them only when the job needs them.
Do I need to change the site URL in Settings after a domain move?
Yes. Update the WordPress Address and Site Address in Settings, then General, to the new domain, with no trailing slash. The search and replace fixes stored URLs, but those two settings control where WordPress thinks the site lives.
Sources
- wp search-replace - WP-CLI Command WordPress Developer Resources
- Migrating WordPress WordPress.org
- Better Search Replace WordPress.org
- Better Search Replace source code GitHub
- How to Run SQL Queries in phpMyAdmin Liquid Web
- Requirements WordPress.org
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


