Moving WordPress to a new domain or server

26th August 2009

WARNING! This post isn’t really for beginners. In any case, please back all your stuff up comprehensively before trying anything out. If you don’t know what you’re doing, things could go quite wrong.

Moving WordPress’s location—be it to a new domain, a new server location, or both—has never been as easy as it might be. Here I’m going to document my own process for achieving this, and try to keep it updated with new ideas and lessons learned.

Please note before starting that I’m concentrating here on the WordPress-specific side of this process. For anything not related to WordPress regarding moving domain or server, you should probably check with your domain registration service or web hosting provider.

1. Lock out all users

Firstly, you should prevent any users from accessing the site. This is so you don’t get any content / comments / etc. submitted after you export the database.

Generally I’m in the situation where I have to move a WP installation from a development domain to a live domain, so this has little impact; but it’s worth doing so anyone adding content (e.g. your client) doesn’t lose work.

If you’re moving a live site, you might be looking at a bit of down time. I won’t be going in to the more general ins and outs of moving a live site for now (sorry!).

There are probably, ooh, umpteen ways of locking users out elegantly. My preferred method is using my 503 holding page, with a filter for my own IP address. If you’re not comfortable with .htaccess the Maintenance Mode plugin should help.

2. Back up files

If you’re moving the location of your files on your server, you’ll need to pay attention to this. If you’re just changing the domain, you may as well back files up, but it’s not necessary.

You can be blunt about this and literally back up all files, but really these are the only WP files that are unique to particular WP installations:

• /wp-content/ (everything in this directory)
• /wp-config.php

While not standard WP files, these are common files that might also be specific to your installation:

• /.htaccess
• /apple-touch-icon.png
• /favicon.ico
• /robots.txt

For any of my clients using my installations, these files also need saving:

• /503.php

See also: A more detailed guide to WP files.

3. Back up the database

The database contents have to change whether you’re moving server or domain.

You can do this using the WP-DBManager or a similar plugin, or via phpMyAdmin (accessible through your host’s control panel).

Here’s a sample phpMyAdmin Export screen showing typical options you’ll need to select:

4. Back up any complex plugin data

For me, this means exporting all stuff from the excellent but fiddly cforms plugin. Back up each individual form, and all the global settings.

5. Make file changes

Do a global search through the site’s files for instances of the absolute server path and/or the domain. Most good editors can search through multiple file contents. I know Dreamweaver does; personally I use TopStyle.

Until you’re familiar with the process, it’s best to check each instance before replacing it.

Replacing the server path

Here’s some places where you might find the absolute server file path if it needs changing:

• /.htaccess (I usually have some .htpasswd protection ready to roll just in case, and the path to that file will be here.)
• /wp-content/plugins/cforms/abspath.php (If you’re running the cforms plugin, this file sometimes needs to be created manually, containing a reference to the server path. Why? Good question. In short, it’s related to AJAX.)

Replacing the domain

Here’s some places where you might find the domain if it needs changing:

• /.htaccess (I usually have a bunch of things in here that need the domain hard-coding: redirects, rewrites, no-www stuff, etc.)
• /robots.txt (For me, usually a reference to the XML Sitemap.)
• /wp-content/plugins/cforms/js/cforms.js (More AJAX-related fiddlyness from cforms.)

6. Make database changes

Here’s where the fun starts!

I’m joking, this bit’s a nightmare. At least, it can be a pain.

You’ll probably need to alter the database contents for any server or domain change.

Character encoding

I still occasionally make a mistake here, but basically you need to check if your database tables are set to UTF-8 or not. If they are, make sure you do any editing of the database export file in an editor that supports Unicode files. I know the latest Dreamweaver and TopStyle do. TextPad does; I think even Notepad does these days, so this might not be as much of an issue as it used to be. (Though Notepad is probably best avoided. Its search/replace won’t be up to the task here, and my experience of it working with multi-megabyte files is patchy.)

I’ve not tried any of these solutions out, but the ace WP developer Vladimir Prelovac has a page and a plugin aimed at solving problems with UTF encoding in WordPress databases.

Anyway, because of character encoding and for other reasons…

Keep an unchanged copy of your original database backup file

We’ll be editing the SQL file your database backup produced, but it’s best to keep the raw, unedited original intact. Make a copy and make changes to that for the new database. Just in case…

A problem: serialized data

The thing that turns doing a “simple” search/replace on our SQL file to switch the server path or domain is that WP, and some plugins, often store settings in the database using serialized arrays.

What’s important here is that this data format will store, alongside a string of characters, the length of that string. If you change the string to something of a different length, it won’t match the stored length, and the data will be “corrupted”. Plugins like cforms include a function that tries to help out if this happens, but my experience of it isn’t reassuring.

I recently found a PHP Serialization Fix for WordPress (by Dave Coveney). Dave offers the code with caveats. I’ve not had time to test it out yet, so even though it’s a PITA, for now I’m sticking with the manual method below. It is possible, with a little patience.

1. Open the copy of your database SQL file in your editor.
2. If you’re changing the server path, do a search/replace to switch the old absolute file path with the new one.
3. Scan through the list that your editor gives from the operation, and look for replacements that look like this (only surrounded by loads of other data, obviously!):

   s:17:"/new/server/path/"

   The s at the start there indicates that in the array this data was serialized from, this value is a string. The number that follows is the length of the string, then you get the string itself. You need to change that number to the length of the new server path for each instance where you can see that it’s been changed in a serialized array.

4. If you’re changing the domain, repeat the above two steps for the domain.
5. Save the file and exit the editor.

My experience is that the number of instances stored in a serialized array where the string lengths need changing, for either server path or domain, isn’t unmanageable. The contexts where either are stored many, many times, are usually not in serialized arrays. A common example is where the site’s content is packed with URLs—either image tag src attributes or links. You may get oodles of these, but the straight search/replace will have dealt with them OK; they’re not in serialized arrays.

7. Get the new site going

Now you’re pretty much set.

1. Import the altered database SQL into a new database (you may as well keep the old one installed for now as an extra backup).
2. If any database information (name, user, password or host) is changing, update the new site’s wp-config.php file appropriately.
3. If you’re moving the files, upload them to the new location. If you’ve only backed up the installation-specific files, upload the other WP core files as well, taking care not to overwrite any of your customized files (especially the /wp-content/ directory).
4. Do whatever you need to switch the domain over, change the DNS, etc. I can’t help you with this bit if you don’t know what to do—ask your server admin.
5. Test the new site before removing whatever method you used to lock other users out!
6. Check your cforms if you use that plugin. If your data didn’t make it through the changes, you can just reset the plugin and import your backed up forms and settings.
7. If you’ve moved your files, you might need to check file permission-related areas such as:
   • WP / plugin upgrading (see this post)
   • The /wp-content/uploads/ folder (see this Codex page)

I hope this has all been of some use to you. While I can’t provide support for basic issues, and certainly wouldn’t recommend a beginner trying all this, please let me know any better ways you have of addressing the same issues, helpful plugins, corrections, etc. Thanks!

Posted in WordPress, databases  |   |  Comments feed