Migrating your entire WordPress site using WP Migrate DB Pro (Deprecated)
In this doc we will go over the nitty-gritty of a WordPress site migration. Many of us know that moving a WordPress site from one host to another isn’t as simple as it could be. The reason being is that WordPress stores full site URLs in serialized data in the database, this makes individual sites not very portable. In this doc we’ll go over the components of a site migration and how WP Migrate DB Pro makes them A LOT more straightforward.
WordPress Background
Before we get into moving things around, let’s briefly define a WordPress site. This will help you understand how to move things around.
A typical WordPress site is essentially two things:
- A file system consisting of PHP files, JavaScript files, CSS files, and media (images, movies, PDFs etc.)
- A database that stores your site’s content
There can be other things involved like web hosts, caching systems and external services, but these are the two major components we’re worried about when running a migration.
Essentially, there are two things you need to worry about when running a site migration: your files and your database.
On the topic of files, there are two types of files that we’ll worry about when running a migration. These types are WordPress core files and site specific files. WordPress core files are what run the WordPress CMS and wire everything together. These files are updated with each WordPress version when you click ‘update’ in the dashboard . Also, as a rule it’s best to never modify core WordPress files, as with any core update your changes would be lost.
The other set of files is your site-specific files – your themes and plugins and your media. These are all located under the /wp-content folder on your site and are generally the main files you are concerned with when running a migration.
With WP Migrate DB Pro, we’re only concerned with your database and your site specific files. WP Migrate DB Pro doesn’t migrate WordPress core files and this has a major benefit, as we’ll soon see.
Running a Site Migration – the old way
Ok, so now we know how WordPress is set up and generally how things work and where they are located. To run a migration, you need to get all your site’s stuff from one place to another. Traditionally, there was pretty much one way to do this: SFTP or SSH.
If you Google ‘WordPress site migration’ you will find a bunch of articles that explain how this method works. It’s basically 4 parts:
- Move all your files from one server to another server via (S)FTP or SSH connection.
- Export your database on the source site (usually a
.sqlfile extension) - Import the database dump file on the destination site using phpMyAdmin or a similar tool
- Run a find & replace on the destination sites database, replacing the old site domain with the new site domain
While this seems fairly straightforward, there are a few gotchas.
If you’re migrating files via FTP or SSH you’ll need a client (program) on your computer to do so. You’ll also need the connection information for the server. These may not be available if you’re working on a client site.
The next question is which files should you migrate? Is WordPress already installed on the remote site? If so, you’ll only need to migrate your wp-content folder, if not you’ll need to migrate all your core WordPress files as well.
The next question is how do you import the SQL dump file? Log in to phpMyAdmin on the remote site? Where are those login credentials? Let’s ask the client…
The last gotcha is that find & replace step on the destination site. It’s not as simple as running a find & replace for your local URL in the exported database dump file. This is because some URLs are stored in serialized data. If you’re not familiar with serialized data, it is a string (text) representation of something in PHP – an array or an object usually. Long story short is that it’s a very specific piece of information that contains a count of the number of characters in the string!
Example of WordPress serialized data:
a:1:{s:4:"site";s:20:"http://mywebsite.com";}
As you can see, serialized data kind of sucks. If you have a URL stored in some serialized data in your database, and you then change that URL and not the character count, the serialized data will be messed up and things will blow up 💥.
Ok Pete, so what am I supposed to do then?
I’m so glad you asked!
Search and Replace options
As with anything else in web development, there are about 100 ways to skin a cat. One of the most straightforward ways is to use WP-CLI. We have a super simple straightforward wp search-replace command:
wp search-replace "http://old-url.com" "https://new-url.com"
Cool, and it even works with serialized data. But what if you don’t have access to the CLI or aren’t comfortable using the terminal? What about installing WP-CLI?
There are other options. One such solution that has been around forever is interconnect/it’s Search Replace DB. It’s pretty straightforward and also works on serialized data as well. To run it, upload the script to your server via SFTP, fill in the values and fire away. This option works well, but it’s an additional file to keep track of and you don’t want it hanging around on your server as it’s not behind any authentication 😱!
That brings us to the last option: plugins. Plugins are a great solution as they have all the benefits of the interconnect/it script but are protected in wp-admin. We may be biased, but we think WP Migrate DB Pro is the best plugin for site migration jobs 💪.
Running a Site Migration – the new way
WP Migrate DB Pro handles all of the above issues with ease. Your database is migrated from one site to another and a find and replace is run (including that nasty serialized data). Not only that, with the Media Files and Theme & Plugin Files addons you can migrate your site-specific files as well! All this with no SFTP/SSH access required!
Alright, this sounds great, how do I run a migration with WP Migrate DB Pro?
Ok, so we have seen how WordPress site migrations can be a pain, so let’s see how to get things running smoothly with WP Migrate DB Pro.
Preamble
WP Migrate DB Pro requires WordPress to be installed on both sites before starting the migration. The reason is obviously that since WP Migrate DB Pro is a plugin it requires WordPress core to run. We also believe that migrating WordPress core files doesn’t make much sense as they don’t change from site to site and should really only be downloaded from WordPress.org. All managed WordPress hosts install WordPress core by default and the rest offer a 1-click WordPress install via their control panel.
Once you have two functioning WordPress installs set up, the next step is to install the WP Migrate DB Pro plugin on both WordPress sites. The plugin zip file can be downloaded from the My Account page on deliciousbrains.com. Once you’ve got the zip, upload the plugin file as you would any other zipped plugin.
We’ll do the same for each of the addon plugins, the Media Files Addon, Multisite Tools Addon, the Theme & Plugin Files addon and the CLI Addon. You can also install the addons from the Addons Tab (go figure) within WP Migrate DB Pro.
For the purposes of this article we’ll assume that you have a Developer level license or higher, granting access to all addons.
Running a site migration with WP Migrate DB Pro
Ok, so now we’ve got two working WordPress installs, and both sites have WP Migrate DB Pro and its addons installed. Lets see how a site migration works.
For the simplest example we’ll run a ‘pull’ migration. A pull migration means you’ll be replacing your local site with the contents of the remote site. A ‘push’ is the opposite type of migration, replacing your remote site with your local site.
To run a pull:
- In your local site (or staging site, wherever you’re starting your migration), log in to your WordPress admin at
http://yoursite.com/wp-admin. Once logged in, go toTools > Migrate DB Pro. - Toggle the ‘Pull’ migration radio button and enter the connection information for the remote site. This can be found by logging in to the remote site, going to the WP Migrate DB Pro page and clicking on the “Settings” tab.
- Once you’ve pasted in the connection information and connected you will be presented with all the options available for the migration.
-
You’ll notice that there are a couple find & replace values already entered by default – bonus! The first row is the URLs to replace and the second row is the file paths for each server. You can add additional find & replace rows here as well.
We won’t go through every option, but there are options to select which database tables to migrate, options to run a database backup (safety first!), and options to migrate media, themes and plugins.
As a default, we’ll select ‘Compare then download’ for the Media Files options, your active theme under the Theme Files and all plugins under Plugin Files. -
Once you’re happy with the selections you’ve made, click on ‘Pull’ and the migration will start.
WordPress media items will be downloaded from your remote server and placed in your local /wp-content folder and your selected themes and plugins will be downloaded as well. The find & replace will be run on your database and everything will be cloned from your remote site to your local site. Easy-peasy.
Once the migration is completed you should have a complete copy of your site running on a new server 💯!
WP Migrate DB Pro vs The Manual Method
As you can see, there are a few benefits of using WP Migrate DB Pro vs the manual method.
The first is that there is no need for SFTP/SSH. Once you’ve installed WP Migrate DB Pro and the addons on both sites you’re ready to go. You’re also able to run a find and replace on your database, so that step is much easier. Lastly, there’s no mucking about with database administration interfaces – everything needed to move your site from one site to another is done within the plugin itself!
Caveats
Whenever I read a piece about how great something is, I always wonder “ok, what aren’t they telling me?”.
While WP Migrate DB Pro makes full WordPress site migrations easier, there are some limitations. Because we’re relying on WordPress and PHP, migrations are constrained to these limitations.
This means that things like post_max_size, memory_limit and other PHP settings may need to be tweaked to get migrations running smoothly. This means that you may need some debugging skills to get migrations working correctly if things go wrong 🕵️♂️.
The other thing that can interfere with migrations is network firewalls and security software. Because we’re sending files over the internet via PHP processes, some software will block our network requests. This usually isn’t an issue with SFTP or SSH connections.
Lastly, WP Migrate DB Pro only migrates files that are present in your WordPress Media Library.If there are any files in your /wp-content/uploads folder that are not in your Media Library, they will not be migrated. This is a known limitation and we plan on remedying this in a future version.