General

Few days back I had noted on this blog that the WordPress 2.3 upgrade of my blog went trouble-free and the blog was inaccessible only for less than a minute during the upgrade. I had quickly noted down the steps that I had followed to do the upgrade and I am trying to give a shape to those rough notes in the hope that it may come handy to me in the future. Whether or not this will be useful to the others depends on whether they share the same environment as that of my blog. Most important factor to me was my web host Dreamhost‘s support for remote shell access which is very helpful in carrying out many of the following tasks conveniently. I find FTP, scp etc. to be slow and inefficient. I was also lucky that my theme and plugins didn’t me give any problems.

So let’s get started.

The general idea here is to create a complete replica of the current blog at a different location but using the WordPress 2.3 version. Such a copy can be made on a local system too(if LAMP stack is installed, say XAMPP) but because Dreamhost makes it so easy to work with the remote shell, I decided to make the copy on the Dreamhost server directly.

1. Let us first get everything ready that is needed to make a copy of the existing blog. We need to create a new directory to install WordPress 2.3 in it and also need to create a new database to import the old posts into it. (If you can’t/don’t want to create a new database, you can use the same existing database and use a new table prefix(e.g. wp2_) instead, but there is always a tiny-weeny bit of risk involved with this.)

   From the control panel of your web host, create a new sub-domain and name it something like blog2.domain.com(you can create just a new directory too like domain.com/blog2); on Dreamhost this creates a new directory with the name blog2.domain.com and I use this directory name in the rest of the post.

   Create a new MySQL database and let’s say you name it wp23_db. You can do this (1) using mysql command in a remote shell(ssh), (2) using phpMyAdmin web interface, or (3) from the control panel(like cPanel); use whatever method is provided by your web host. Note down the host name, user name and password details for the created database for future reference. On most web hosts the MySQL host name will be localhost, but on Dreamhost it will be mysql.domain.com.

2. Download WordPress 2.3 and extract it in the newly created directory, probably using FTP, like you might have always done. Or preferably, use subversion to install WordPress 2.3 this time. If you use Dreamhost, you can connect using ssh/putty and run the following commands:
   sh# cd $HOME/blog2.domain.com
   sh# svn co http://svn.automattic.com/wordpress/tags/2.3 .
3. Copy the content files(theme files, uploaded files etc.) from your current blog directory to the new directory:
   sh# cp -rpf ../oldblog/wp-content/* wp-content
   sh# svn up

   Also include any other directories you might have created to store non-Wordpress files like images.

4. Now import all the data from the old database to the newly created one. You may prefer to export/import from the phpMyAdmin interface, which makes it a very easy task but painfully slow, so I use the command line instead:
   sh# mysqldump ––add-drop-table -u -p -h mysql.domain.com > exported.sql
   sh# mysql -u -p -h mysql.domain.com wp23_db < exported.sql

   Remember to use *your* username, password, MySQL host name and database name in the commands.

   You might consider disabling all the plugins in your current blog *before* exporting the database and then re-enable them as soon as the export job is finished. Actually it is strongly recommended that you disable the plugins before exporting the database as it may be necessary in your case depending on what plugins are installed on your blog. For the record, I didn’t have to disable the plugins(I was using the 3.0 beta version of Google Sitemap and latest versions of all other plugins).

5. The database is ready now with all your posts in it. Next enter the database details of this *new* database(wp23-db) in the wp-config.php of the new 2.3 installation:
   sh# cd $HOME/blog2.domain.com
   sh# cp wp-config-sample.php wp-config.php
   sh# emacs -nw wp-config.php

   [php]
   define(‘DB_NAME’, ‘wp23-db’); // The name of the database
   define(‘DB_USER’, ‘username’); // Your MySQL username
   define(‘DB_PASSWORD’, ‘password’); // …and password
   define(‘DB_HOST’, ‘localhost’); //mysql.domain.com in case of Dreamhost
   [/php]

6. Before we can access the administration area of the new blog we need to edit a field in the database. Change the value in wp_options -> siteuri and wp_options -> home fields in wp23-db database i.e. replace the old blog URL with the new URL(i.e. change http://oldblog.domain.com/ to http://blog2.domain.com/ – either use phpMyAdmin or the mysql command to do this). (This is a cumbersome step and I think the URLs should be stored in a configuration file instead of in the database.)
7. We are ready to run the upgrade script now, go to http://blog2.domain.com/wp-admin/upgrade.php to do so. You can now access the new, shiny WordPress 2.3 powered blog at http://blog2.domain.com/ :)
   If you can’t access your blog at the new URL, try:

   1. Copying your old .htaccess file to the new directory:
      sh# mv $HOME/oldblog.domain.com/.htaccess   $HOME/blog2.domain.com
   2. Going to the Options -> Permalinks page in the WordPress administration area of the new blog and clicking the Update button.

   In case parts of the blog look broken or you see database errors referring to tables such as post2cat, some of the plugins may be at fault, see the next step.

8. If you had disabled the plugins in your old blog before exporting the database(Step 4), then obviously the new blog will start with all of them disabled as well. Try enabling them one by one and see if any of them cause any trouble, in which case, consider upgrading the problematic plugins to their latest versions, or simply disabling them until you find a solution to it. You can read more about which plugins are compatible with WordPress 2.3.

   If your theme looks broken, then you can try to fix the incompatible code yourself or try to use a new, 2.3 compatible theme. The chances of a theme breaking disastrously is extremely rare if you ask me. Rich’s article has a workaround.

9. If you are happy with the working of the copy of your blog at http://blog2.domain.com/, it is time to make the final switch from the old blog to the new one. (Note that the old blog was serving your readers faithfully all this time without being affected by all the upgrading stuff we have been doing in the background). This is a critical step and you should confirm multiple times that your WordPress installation and the database backups are in sound size and shape before proceeding further. Do this as part of the final step:
   1. Change the URLs to point to your original blog location:
      Go to http://blog2.domain.com/wp-admin, change the values in Options -> Blog Address and Options -> Website Address to http://oldblog.domain.com/. You can change the URLs directly in the database too, like we did in Step 6.
   2. sh# mv oldblog.domain.com tempblog.domain.com && mv blog2.domain.com oldblog.domain.com

      Your web host may instead support mapping of domain names to directories in a different way. Use whichever way is available to you to map the old blog URL to the new installation directory. If you think something has gone wrong, then you have to reverse only this particular step.

   You can now access the upgraded version at http://oldblog.domain.com/
   (Delete the old database, old installation directory and the new sub-domain if you like.)

That’s it. Did I goof-up somewhere? I hope you at least got the gist of the method of upgrading described above. While enjoying the new features of the 2.3 version, try to make some time to read useful posts about WordPress 2.3 on the web. Mine was a success story, you may want to read about a different, not-so-positive WordPress 2.3 upgrading experience too. I could add a few more miscellaneous points such as how FTP too can be used instead of a shell to achieve the same end result but I think we would agree that the post is already quite long :)