CraftRoq Relocate DB guide

Change a web address everywhere on a site, safely, with a preview before anything is changed.

This guide shows how to change a web address, or any piece of text, everywhere on a WordPress site: for example after moving the site to a new address. The plugin always shows you what it would change before it changes anything. You do not need to know anything about databases.

Chapter 1 of 11

Before you start

What the plugin does, when you need it, and the one thing to do first.

Your site keeps its pages, settings and menus in a database. The site’s own address is written in there thousands of times. When the address changes, every one of those has to change too, or links and pictures break. CraftRoq Relocate DB finds them all and replaces them safely.

You would use it when you:

  • move a site from a test address to its real address;
  • switch a site from http:// to https://;
  • change the site’s domain name;
  • need to correct a name or phrase that appears all over the site.

First, take a backup

Before replacing anything, make a full backup of your database. Most hosting companies have a one-click backup, or will do it for you if you ask. The plugin keeps its own safety copy of what it changes, but that is not a substitute for a backup.

You need: a WordPress site (6.5 or newer, PHP 8.1 or newer) that you can log in to as an administrator. The plugin does not run on a WordPress Multisite network.

Back to the list of chapters

Chapter 2 of 11

Install the plugin

  1. Get the file

    On the CraftRoq Relocate DB page, press Download free and follow the steps. You end up with a ZIP file.

  2. Upload it

    In WordPress go to PluginsAdd NewUpload Plugin, choose the ZIP and press Install Now, then Activate.

What you should see

A new entry called Relocate DB in the menu on the left. Opening it shows five tabs across the top: Dashboard, Search & Replace, Import / Export, History and Settings.

Back to the list of chapters

Chapter 3 of 11

Change an address everywhere

The whole job is three steps: say what to change, look at the preview, then confirm. Nothing is changed until the last step.

Step 1: say what to replace

  1. Open the plugin

    Go to Relocate DB. You are on the Dashboard.
    The Dashboard.

  2. Type the old address

    In Find, type the address as it is now, for example https://staging.example.com. Type it exactly, with no / at the end.

  3. Type the new address

    In Replace with, type the address it should become, for example https://example.com.

  4. Continue

    Press Continue.

More than one thing to change?

Press Add another for each extra pair. You can have up to 20, and they are all done in one go.

Step 2: choose where to look

  1. Leave the recommended choice

    Keep All WordPress tables selected. It is marked as recommended, and is right for almost everyone.
    Where should it look?

  2. Start the preview

    Press Preview changes.

Step 3: look at the preview, then apply

  1. Wait for the dry run

    The plugin now reads through your database. This is called a dry run: a rehearsal that changes nothing. A bar shows how far it has got.
    The dry run in progress.

  2. Read the result

    When it finishes you see Dry run complete. Nothing in the database was changed. Below are the number of rows that would change, and examples showing the text Before and After.
    The preview. Check that the “After” lines look right.

  3. Happy? Apply it

    Press Replace in database….

  4. Confirm

    A box asks Replace in the database? Leave the tick beside Save the original value of everything that changes to a downloadable file (recommended), tick the box to say you have a backup, and press Replace now.
    The last check before anything is written.

What you should see

The job finishes with the status Completed. If you changed the site’s own address, WordPress logs you out: log in again at the new address.

Not happy with the preview?

Press Change search and correct what you typed. Nothing has been changed, so there is nothing to undo.

Back to the list of chapters

Chapter 4 of 11

What to type for common jobs

In each case, type the left-hand text in Find and the right-hand text in Replace with.

Test site to real site
https://staging.example.com becomes https://example.com. If the site’s folder on the server changed as well, press Add another and add the old and new folder, for example /home/staging/public_html and /home/live/public_html. Your hosting company can tell you these.
Switch to https
http://example.com becomes https://example.com.
New domain name
https://old-name.example becomes https://new-name.example.
Remove a piece of text
Type it in Find and leave Replace with empty.

Catch every version of the address

On the “Where should it look?” screen, open Advanced options and tick Include other versions of the URL. For https://old.com it then also replaces http://old.com and //old.com.

The other Advanced options, in plain words

Ignore upper and lower case
“Example” also matches “EXAMPLE” and “example”.
Match whole words only
“cat” matches “cat.” but not “concatenate”.
Leave post GUIDs unchanged
Leave this ticked. A GUID is a hidden label that news-reader apps use to recognise posts they have already shown.

Back to the list of chapters

Chapter 5 of 11

Put things back

There is no undo button, but the plugin keeps what it changed.

If you left the “save the original value” tick on (it is on unless you remove it), every replacement keeps a file of the old values.

  1. Find the job

    Go to Relocate DBHistory and open the replacement you want to reverse.
    History: every dry run and replacement.

  2. Download the original values

    Press Download original values (.sql.gz) and keep the file.

  3. Give it to your host, or import it

    Importing that file into the database puts the old values back. If you have not done this before, send the file to your hosting company and ask them to import it. They do this every day.

Do it soon

Importing the file also overwrites any edits made to those same values since. Put things back straight after the replacement, not weeks later.

Back to the list of chapters

Chapter 6 of 11

If it stops part-way

A closed laptop or a dropped connection does not break anything.

The plugin works through your database in small pieces and saves its place after each one. Each piece is either finished completely or not done at all.

  1. Open the plugin again

    Go to Relocate DB. The job is listed under Recent jobs, marked Needs attention.

  2. Continue it

    Open the job and press Resume. It carries on from where it stopped.

Back to the list of chapters

Chapter 7 of 11

Move a whole site’s database

The Import / Export tab copies everything from one site to another, and can change the address on the way.

On the site you are moving from

  1. Open Export

    Go to Relocate DBImport / Export and stay on Export database.
    Export the database.

  2. Change the address as it leaves (optional)

    Under Change text while exporting, type the old address in Find and the new one in Replace with. Your database on this site is only read, never changed.

  3. Export

    Start the export. When it is ready, press Download export. The file’s name ends in .sql.gz.

On the site you are moving to

  1. Open Import

    Install the plugin there too, go to Relocate DBImport / Export and press Import database.

  2. Save what is there first

    The screen suggests you Export this site first, so you can go back if you need to. Press Export now and keep that file.

  3. Choose your file and import

    Under Database file, choose the file you downloaded, confirm, and wait.

What you should see

The site keeps working while the import runs. The new contents are prepared alongside and swapped in together at the very end. If the import fails or you cancel it, the site is left exactly as it was.

The same settings on every site

The third view, Settings file, lets you Download settings file on one site and Import settings on another.

Back to the list of chapters

Chapter 8 of 11

History and settings

History

Relocate DBHistory lists every job. Use All, Dry runs and Replacements to narrow it, or the search box. The Log view beside Jobs is a detailed diary that support may ask you for.

Settings

Rows per batch
How much is done in each small piece. Leave it as it is unless support suggests a change.
Keep history for
How many days jobs, logs and export files are kept before they are tidied away.
Delete all plugin data when the plugin is deleted
Removes the history, logs and settings if you delete the plugin. Your site’s own content is never affected.
System status
A second view with facts about your server. Useful to copy into a support request.

Back to the list of chapters

Chapter 9 of 11

For developers: the command line

You can skip this chapter. It is for people who manage sites with WP-CLI.

The same jobs can be run from a terminal. They appear in History like any other.

# See what would change. Nothing is written.
wp crq search-replace https://staging.example.com https://example.com --dry-run

# Replace, after confirming.
wp crq search-replace https://staging.example.com https://example.com

# Continue a job that stopped, by its number in History.
wp crq resume 42

Run wp help crq search-replace for every option.

Back to the list of chapters

Chapter 10 of 11

If something goes wrong

What each message means, and what to do.

“The dry run found nothing to replace.”
The text in Find is not in the database as typed. Check the spelling, and whether it should be http or https, with or without www.
“Only a completed dry run can be applied to the database.”
The preview did not finish. Open the job and let the dry run complete first.
“Another replacement is still running.”
Wait for the other job to finish, or open it and cancel it.
“This dry run has already been applied.”
That preview has been used. Start a new one from Search & Replace.
A table was skipped
Some tables cannot be changed one row at a time safely, so the plugin leaves them alone and says so in the results. This is rare for WordPress’s own tables.
Some values were “left unchanged”
The plugin will not alter a value it cannot change safely, for example one that was already damaged. They are listed so you can look at them.
I am logged out after replacing
That is expected when the site’s address changes. Log in at the new address.
The plugin says it does not run here
The site is part of a WordPress Multisite network, which this version does not support.

Still stuck?

Tell us what you typed and what the screen said. For free plugins we help when we can.

Back to the list of chapters

Chapter 11 of 11

Words used in this guide

Backup
A complete copy of your site’s database, kept somewhere safe, so you can go back to it.
Database
Where WordPress keeps your pages, posts, settings and menus.
Dry run
A rehearsal. The plugin works out what it would change, and changes nothing.
GUID
A hidden label on each post that news-reader apps use. It should normally be left alone.
Job
One dry run or one replacement.
Serialized data
A way plugins store settings in which each piece of text is saved with its length. Changing the text without correcting the length breaks the setting. The plugin corrects it for you.
Table
One part of the database, such as the one that holds your posts.
URL
A web address.

Back to the list of chapters