The WordPress core and the plugins you install on your site store several references to the site's URL and the server's path structure inside the database, either as text or as PHP serialised data. The latter is a special encoding format used by PHP to allow developers store structured data in a database text field. As you're painfully aware, this data is extremely difficult to modify when you are transferring your site to a new server, subdomain, domain, or directory. This part of BRS handles that for you, allowing you to safely replace these references in your database, be it text or serialised data.
Replacements to be made
In this section of the page you can specify which data will be replaced, and what its replacement will be. BRS populates this section based on the old and new site's URL, and path in the server's filesystem. Each replacement necessary is included in all the different forms it might be appear in the database.
If you need to add more replacements (for example, change references to the title of the site) you can do so. Go to the empty line at the bottom of the list. The left-hand box is the text to match. The right-hand box is the text to replace it with. After entering a new line, click on some whitespace on the page; a new blank line will appear at the bottom of the list.
You can remove a replacement line using the red button with the trashcan icon.
Please remember that the replacements are processed in the order shown. If you add custom replacement lines you may need to reorder them. Use the up and down arrow icons towards the right-hand side of each row to change that row's ordering.
Database tables
This is where you can select where the replacements will take place.
The Include post GUID in data replacement option, allowed by default, will replace the GUIDs (unique IDs) of posts and media items when enabled. This is generally recommended when you are moving your site to a new domain, subdomain, or subdirectory. However, this means that a user who uses the new site's RSS feeds will experience that all previously seen posts are shown as new. That's because these posts' unique IDs have changed. Generally speaking, you should enable this option unless you have a specific use case which requires the old GUIDs to remain stable.
Below that, you will see a list of database tables. By default, BRS will only replace data in specific core WordPress tables where we know for sure there is data which needs to be replaced. If you want to extend the data replacement to other tables, for example those used by third party plugins, select them from the list. You can use CTRL-click (Windows, Linux) or CMD-click (macOS) to select individual tables. Clicking on a table name and then pressing CTRL-A (Windows, Linux) or CMD-A (macOS) will select all tables.
![[Tip]](/media/com_docimport/admonition/tip.png) | Tip |
|---|---|
|
If you are not sure what to do here just leave all tables unselected and click on Next. If you see that some plugins reference data from the site you backed up from after the restoration is completed you can redo the restoration and select more / all tables here. |
Advanced options
The options control how the replacement algorithm works.
- Maximum column size
-
Data will be replaced in database columns which contain data at most this many bytes long. The default is 1048576 bytes (1 MiB). Larger columns may require a lot more time to process which could lead to a timeout and restoration failure.
- Batch size
-
Up to this many database records will be processed at once. The more records being processed at once, the more memory, CPU, and time will be consumed in each individual replacement step, but also the less steps will be required overall.
Default: 100. Increase to 1000 or even 10000 if you have a generous memory limit (256M or more), and a fast server.
- Minimum execution time
-
Each step will have to run for this many seconds. Increase this to reduce the number of requests per second made to your server.
Default: 0 seconds
- Maximum execution time
-
Each step will run for up to this many seconds. Increasing it will use more memory and CPU resources, but make the replacement process faster.
Default: 3 seconds
- Runtime bias
-
A multiplier for the maximum execution time. When the Maximum execution time times Runtime bias is exceeded when a step needs to decide if it will do some more work, it will stop and return execution.
| Tip |
|---|---|
|
These settings are very useful when you have a very fast, or a very slow server. On a very fast server with a generous memory limit (256M or more), a large execution time limit, and a fast processor use Minimum execution time 0, Maximum execution time 10, Runtime bias 90, and Batch size 10000. This will make the data replacement step go significantly faster on large sites. On a restrictive shared host use the default settings. On a very restrictive shared host use Minimum execution time 7, Maximum execution time 5, Runtime bias 80, and Batch size 100. The effect of the minimum time being more than the maximum is that there's 2 to 3 seconds of "dead time" between each step. It makes the replacement run twice as slow, but it also addresses the problem of hitting a CPU usage, request frequency, or queries per minute limit on your server. If you have to use settings like that to get your site running, use a different host. It's not the 2000s anymore; you can find far better quality hosts for dirt cheap. |
Finally, click on the button to let ANGIE write your site's new configuration and display the final page.
Data replacement and WordPress multisites
WordPress allows you to create multisite installations. These fall under three broad categories:
-
Installed on the root of the domain, using subdomains for the multisites. For example: http://example.com (main site), http://child1.example.com, http://child2.example.com (child sites).
-
Installed on the root of the domain, using subdirectories for the multisites. For example: http://www.example.com (main site), http://www.example.com/child1, http://www.example.com/child2 (child sites).
-
Installed on a subdirectory of the domain, using subdirectories for the multisites. For example: http://www.example.com/myblogs (main site), http://www.example.com/myblogs/child1, http://www.example.com/myblogs/child2 (child sites).
The Replace Data page is aware of these kinds of sites, as well as standard, single-site installations. It will automatically include the necessary replacements required to transfer your site to the new location. However, you cannot convert all types of multisite installation to another, or convert between a multisite and a single installation due to restrictions in how WordPress works.
You CAN NOT convert from a Type 1 site to a Type 2 or 3 site and vice versa. In other words, if you have a multisite with subdomains it has to remain a multisite with subdomains. If you have a multisite with subdirectories it has to remain a multisite with subdirectories (you can only move it between the root of the domain and a subdirectory).
You CAN NOT restore a multisite installation with sudomains to a subdirectory. WordPress only allows this type of multisite installation in the domain's root.
You CAN NOT extract a single "site" from a multisite installation. In fact, these "sites" are not real "sites". WordPress is merely employing some fine trickery to give you the illusion of multiple sites. All of the sites are weaved together. You can try to restore the full multisite installation, delete all sites except the one you want and use some instructions of dubious quality you can find on the Internet to convert the multisite WordPress installation to a single site installation. According to client feedback this is a hit and miss operation. It's usually better to export the content and import it to a new site (and put a lot of work to rebuild the new, single site installation to resemble your old site), or not use the WordPress multisite feature to begin with unless you fully understand what is going on.
Technical notes on data replacement
We use a carefully calibrated algorithm to replace data in both plain text and serialised PHP data formats. Furthermore, our data replace solution uses our stepping algorithm to make sure that there is no PHP or server timeout while replacing data in your database instead of trying to replace data in all rows of a table, regardless of how bit it is, which could lead to a timeout or memory issue.
There are only three limiting factors outside our control.
The first limiting factor is a limit on the number of database queries per hour or per minute which may be imposed by your server. Replacing data requires reading your entire database contents in memory, replacing the data and then writing the changed contents back to the database. If you get an error while replacing data please contact your host and ask them to temporarily raise the queries per hour limit for your account. A limit of 100000 (one hundred thousand) queries per hour is enough on most servers. They can restore your much lower limit after the restoration is complete.
The other limiting factor is that data can only be replaced on tables having a primary key. In any other case it will be impossible for your database server to know how to write the modified data back to the database. We have applied a workaround which works in most such cases but be advised that there might be a very rare occasion where some data might not be replaced.
The final limit is the maximum execution time / maximum CPU time allowance. Parsing serialized data is an intensive process. We have taken all steps possible to minimize the amount of work your host's processor will need to perform during that step. However, if you have very large blocks of serialized data (around 1Mb or more) you may run into a situation where either the PHP execution time limit is reached or the host blocks your IP temporarily due to excessive CPU usage. There is not a whole lot we or you can do about it. Doing something difficult requires effort. If your host doesn't let their server expend that effort the work can be done, ergo the site cannot be restored. Sort of using a different host or a more expensive hosting package (with higher execution allowances) there is nothing you can do.
Finally please note that the data replacement only works for database data. Data stored in files cannot be replaced. Storing configuration in files is very rare in WordPress plugins since most developers use the WordPress API which stores configuration in the database. Therefore we consider this case to be extremely unlikely.