In this article, you will learn what the Search and Replace function of WordPress CLI is and how to use this feature. You will also learn what WordPress CLI is.
What is the Search and Replace Function?
Search and Replace is one of the most powerful and advanced features of WordPress CLI. This function searches for a string through all the rows in a selection table and replaces it in bulk with another string. A handy feature of wp search-replace is its ability to not only scan the entire database but also unpack JSON payloads within the database, performing its tasks on them at the same time.
Tip
A string is one of the data types supported by PHP, and it is a collection of characters. The string variable contains alphanumeric characters.
The search and replace command uses a table registered to the $wpdb object. On multisite this will just be the tables for the current site unless --network is specified. It is a convenient tool when changing the site’s URL or any other frequently appearing text inside the database. This tool can save a lot of time when compared to manually updating these values and is much easier than crafting a raw MariaDB query to do the same thing.
WP-CLI is pre-installed on all the servers deployed on Cloudways. The steps below will demonstrate how you can operate WP-CLI and update the password.
What is WordPress CLI?
WP-CLI is a command-line interface for WordPress. It is a set of command-line tools for managing WordPress installations on a server. It allows the WordPress admin users to carry out different administrative tasks without actually using a web browser. This management through the command-line interface enables users to take care of their WordPress websites by executing a set of defined commands. The scope of the tasks mainly includes upgrades, database backups, publishment of new posts, etc.
How to Use the Search and Replace Function of WP-CLI
Here are a few simple steps to help you get started with using the Search and Replace function. It is highly recommended to take a backup of the application data before using the search-replace function so you can always restore it in case of any error.
Step# 1
First of all, you need to connect to your server remotely via SSH so you can use WP-CLI.
If you would like to know what is SSH and why it is used, then Click Here to find out. In this example, we are using Master Credentials to access the server remotely.
You can connect to your server via SSH in two ways, so choose your preferred option from the below options. You can also click on the hyperlink text of bullet points to learn about connecting remotely to the server.
Using SSH Client.
Using the Cloudways Integrated SSH Terminal.
In this example, we have used an SSH client named PuTTY. You will see a similar window after successful connection as shown below:
Step# 2
Now, you need to go to that specific directory where your webroot is located. In other words, where your wp-config.php file is located else, WP-CLI will not work. By default, it is in the public_html directory and we will also follow the default path to operate WP-CLI in this example. Enter a command mentioned below to go into the public_html folder.
cd applications/<your_application_name>/public_html/
Important
Angle brackets are included to indicate the positions of your inputs so make sure to remove the angle brackets. Your application name is the same as your Database name (DB name). Click Here to find out where your application name is located.
You will see a similar window after running the above command successfully.
Step# 3
You may start using WP-CLI once you are in the public_html directory. We have quoted an example below to demonstrate the usage of this tool.
For instance, the command below replaces one string with another and saves changes in the database. Also, this command restricts this tool to search and replace a string in a specific table.
wp search-replace <'old'> <'new'> <table>
For example: wp search-replace 'foo' 'bar' wp_posts
<‘old’> = A string to search for within the database.
<‘new’> = Replace instances of the first string with this new string.
<‘table’> = your database tables such as wp_posts, wp_terms etc. You can also see and manage your database and its tables easily using the Cloudways Database Manager.
Tips
Here are a few helpful tips that can help you while using the search and replace function.
How to view data changes/replacements using this tool before saving in the database?
The --dry-run switch is one of the most helpful flags of WP search-replace. This flag replaces the string with another one but does not save it in the database or, in other words, shows you a preview of the changes that can be made if run without a flag of --dry-run. This flag can be applied at the end of the above command.
wp search-replace <'old'> <'new'> <table> --dry-run
For example: wp search-replace 'foo' 'bar' wp_posts --dry-run
Important
The wp search-replace function is somewhat peculiar in its case sensitivity. For best results, match cases exactly and search for other capitalization instances using the --dry-run option. For instance, this searches and replace function entertains the string “Bar” and “bar” differently because of being case sensitive.
Also, see some useful options (parameters) and their functions below:
More Parameters
Command | Description |
<old> | A string to search for within the database. |
<new> | Replace instances of the first string with this new string. |
<table>… | List of database tables to restrict the replacement to. Wildcards are supported, e.g. wp_*options or wp_post* . |
--dry-run | A string containing the user’s URL for the user’s website. |
--network | Search/replace through all the tables registered to $wpdb in a multisite install. |
--all-tables-with-prefix | Enable replacement on any tables that match the table prefix even if not registered on $wpdb. |
--all-tables | Enable replacement on ALL tables in the database, regardless of the prefix, and even if not registered on $wpdb. Overrides --network and --all-tables-with-prefix. |
--export=<file> | Write transformed data as SQL file instead of saving replacements to the database. If <file> is not supplied, will output to STDOUT. |
--export_insert_size=<rows> | Define a number of rows in a single INSERT statement when doing SQL export. You might want to change this depending on your database configuration (e.g. if you need to do fewer queries). Default: 50 |
--skip-tables=<tables> | Do not perform the replacement on specific tables. Use commas to specify multiple tables. Wildcards are supported, e.g. wp_*options or wp_post* |
--skip-columns=<columns> | Do not perform the replacement on specific columns. Use commas to specify multiple columns. |
--include-columns=<columns> | Perform the replacement on specific columns. Use commas to specify multiple columns. |
--precise | Force the use of PHP (instead of SQL) which is more thorough, but slower. |
--recurse-objects | Enable recursing into objects to replace strings. Defaults to true; pass --no-recurse-objects to disable. |
--verbose | Prints rows to the console as they’re updated. |
--regex | Runs the search using a regular expression (without delimiters). Warning: search-replace will take about 15-20x longer when using --regex. |
--regex-flags=<regex-flags> | Pass PCRE modifiers to regex search-replace (e.g. ‘i’ for case-insensitivity). |
--regex-delimiter=<regex-delimiter> | The delimiter to use for the regex. It must be escaped if it appears in the search string. The default value is the result of chr(1). |
--regex-limit=<regex-limit> | The maximum possible replacements for the regex per row (or per unserialized data bit per row). Defaults to -1 (no limit). |
--format=<format> | Render output in a particular format. |
--report | Produce report. Defaults to true. |
--report-changed-only | Report changed fields only. Defaults to false, unless logging, when it defaults to true. |
--log=<file> | Log the items changed. If <file> is not supplied or is “-“, will output to STDOUT. Warning: causes a significant slowdown, similar or worse to enabling --precise or --regex. |
--before_context=<num> | For logging, the number of characters to display before the old match and the new replacement. Default 40. Ignored if not logging. |
--after_context=<num> | For logging, the number of characters to display after the old match and the new replacement. Default 40. Ignored if not logging. |
Source: WordPress CLI
You have learned how to operate the search and replace the function of WP-CLI. Click Here to see a use case of the same tool. It explains how to manually update the WordPress domain name.
That’s it! We hope this article was helpful. If you need any help, then feel free to search your query on Cloudways Support Center or contact us via chat (Need a Hand > Send us a Message). Alternatively, you can also create a support ticket.