How to Upgrade from Drupal 5 to Drupal 6 - Steps 3 and 4: Actual Upgrade and Testing

latest drupal release graphicToday I finish up the series of articles about upgrading from Drupal 5 to Drupal 6. Earlier posts in the series included: Finally Time to Upgrade to Drupal 6, How to upgrade Drupal 5 to Drupal 6 - Step 1: Planning and Step 2: Getting Drupal 5 Upgrade Ready

The first few posts were all about getting you to the stage where you can actually go ahead and upgrade your Drupal installation. In 25 words or less, do rigorous planning and take several actions to prepare your Drupal 5 site for upgrade before upgrading to Drupal 6.

In this post I finally tackle the actual Drupal upgrade process and include some final thoughts on testing your success.

Test Run

Before I get started, I just wanted to mention that you should always test your upgrade procedures before attempting an actual upgrade. If you have your own deployment methodology with version control and development and staging servers you will have some sort of process in place for "green lighting" a live upgrade. If you have such a process, follow your own best practices.

On the other had, if you don't yet have such a process in place, I would strongly encourage you to attempt your upgrade on a copy of your site before attempting an upgrade on your live site. Even after planning and preparation, there are any number of gotchas that might come along and its better to discover those during a test run. Even if the actual upgrade appears to go smoothly and error free, you may discover that your content (or the way you create content) didn't upgrade properly. Once again, it's best to catch problems and formulate solutions before attempting the upgrade on your live site.

Upgrading to Drupal 6

In the "Step 1" post, I encouraged you to read UPGRADE.txt. Since the writing of that article just a few days ago, UPGRADE.txt has been updated with some more information (such is the world of a fast moving open source community). As a result you may want to re-read that document if you've been reading this series as its been published.

Here I will go through the steps in the updated revision (January 15th 2009).

First Steps

The first few instructions are fairly simple:

  • Back up your site (see my notes in the previous post about backups)
  • Log into your site as user 1
  • Put your site into 'off-line' mode
  • Switch your theme to "Garland"

Disable all Custom and Contributed Modules

In the planning phase you should have created an inventory / checklist of all modules you had installed as well as the sub-modules or components that were enabled. Follow your checklist and disable all of those modules in Administer » Site Building » Modules.

Because some modules depend on others, you may not be able to disable everything in one step. If a checkbox is 'grayed out' next to a module it means that another module depends on that module and is still enabled. You will first have to disable those dependencies.

Out with the Old and In with the New

The next step requires you to remove the old Drupal files from your installation directory. This includes all the files in the root directory (e.g. index.php, .htaccess etc.) and all the Drupal folders (e.g. modules, includes, etc.). Obviously when you do this your site will be completely inaccessible since it won't have any files in place to handle requests.

So the next step is to unpack the Drupal 6 files and folders and put them into your installation directory.

Re-Configure Your Installation

From UPGRADE.txt

Copy your backed up "files" and "sites" directories to the Drupal
installation directory. If other system files such as .htaccess or
robots.txt were customized, re-create the modifications in the new
versions of the files using the backups taken in step #1.

Please note that by restoring your 'sites' folder you will also be restoring the 'modules' folder(s) contained within it. Since this is coming from your backup, those modules folder(s) will contain modules for Drupal 5.x. Therefore, it is a good idea to empty out the modules folder(s) you have under the sites folder before moving onto the next steps. This will reduce the likelihood that you accidentally leave and old Drupal 5.x version of a module in place and forget to replace it with its Drupal 6.x version. Or worse, by leaving the folders in place, you may accidentally merge the contents of the Drupal 6.x version of a module folder with the old Drupal 5.x version.

Run Update.php

You now run update.php by going to http:// yourdomain/update.php and follow the instructions. This script does the work of upgrading the Database preparing it for use with Drupal 6.x. Note, that you are doing this immediately after you have upgraded the Drupal core installation files and folders but BEFORE you have replaced/upgraded any contributed or custom module folders.

Upgrade Contributed Modules

In the planning stage you made a list of modules and did some research on their upgrade path. You made sure that there were Drupal 6 versions of those modules and if not you researched some alternatives you may have to use instead. You also made note of any special upgrade requirements for your modules. By getting Drupal 5 upgrade ready you updated your contributed modules so they could follow the proper upgrade path. You also downloaded all the Drupal 6.x version of those modules (along with any new dependencies they may have).

Now, following your module checklist, install each of your contributed modules. In most cases you do this as you normally would with a fresh install of Drupal. Place the folders in the sites/all/modules folder and go to Administer » Site Building » Modules and re-enable the modules. But, some modules may have special instructions. For example CCK has a specific upgrade instructions for moving from Drupal 5 to Drupal 6. Make sure to follow those upgrade instructions carefully.

Re-run Update.php

After you've got your modules in place and re-enabled you will have to run update.php again by going to http:// yourdomain/update.php. This time it will upgrade the database tables used by your modules.

Re-enable the Drupal 6.x version of your theme

If you had a custom theme, in getting Drupal 5 upgrade ready you migrated that theme to Drupal 6. Otherwise you downloaded a Drupal 6.x compatible theme. In either case you can now enable it.

Testing and Finishing Up

With all that done, your site is now technically 'upgraded'. But, before you declare success and go off to upgrade your live site, you will want to look into a few things.
Did you miss anything? Is there anything on your planning document that you forgot to do? Did you remember to enable every sub-module?
Did your data survive the upgrade? Is published content still published? Are comments still being displayed?
Are your menus intact?
Have you checked the permissions page? Have modules introduced new permissions or taken old ones away? Do these changes impact your site?
Can you create new content error free? Have you tried to create content with all your different content types?
Did your theme migration work perfectly? Were there some parts of the theme you couldn't test until you completed the upgrade?
What else can you think to test?

In the end, you know your site better than anyone and you know what things you will want to test to ensure that everything still works. Only you will know if your upgrade was a success.

Once again, please feel free to leave comments along with your own suggestions or links that may be helpful to others. I covered a lot of ground in the past few posts, but I certainly may have missed some things along with way. I'll be sure to update these docs with information from your comments.

January 15th 2009 12PM
By: andre



mysql database

going from d5 to d6, what do I do with the d5 mysql database that has tables besides the drupal install tables?

d5 database becomes your d6 database

If you upgrade your site following the steps in this article, your D5 database is upgraded to D6.

At no point in this upgrade method would you run install.php for the D6 site.

Upgrade Problems

Thanks for the instructions, they have been very helpful.

I have spent a LONG time trying to upgrade my several sites to d6. I have followed all instructions very carefully, but I always stumble at the same two points:

- CCK fileFields are INACTIVE, i.e. the system pretends the the 'file upload' widget is not activated. That's not true.
- CCK ImageFields are active, but without content. This could be a follow-up of the first problem.

I am getting desperate. Smaller sites can be rebuilt and filled with copy and paste, but there are thousands of pics and uploads in the larger ones.

Do you know of any remedy? Or of any instructions on what to do the database to fix these issues?

Many thanks for any hint


With regard to CCK.
I am assuming you started from a fully updated 5.x site (i.e. all the contrib module were brought up to date before starting). This is particularly important for CCK which has so many 'sub modules' in the form of fields.

Image field in particular has gone through many changes so you have to be very careful with getting it upgraded.
CCK has fairly detailed upgrade instructions. Be sure you follow those exactly. The order in which you enable things and run update.php matters.

Even I ran into a glitch upgrading one CCK content type. The good news is that you have backups - and your doing this on a test run (i.e. not your live site - see the "Test Run" section above). Go to the last known working state of things and start over making sure you are following the CCK and field upgrade instructions exactly. In my case I had done something out of order in my test run and when I adjusted the order and did another test run it just worked.


*edit*p.s. Also make sure that when disabling contributed modules prior to upgrade you get all of them disabled. See notes on that above too.