I had some real “fun” today (about a full day’s worth) after upgrading one of my Drupal installs from 7.7 to 7.8. The whole site went awry: the template no longer showed, I was only getting text, I kept getting either 404 or 500 errors when clicking on links, and nothing I did seemed to make it better. Even restoring from a backup yielded the same garbled pages. It’s fixed now and working perfectly (well, not perfectly, because some modules are still in beta and there will always be some errors, but it’s working as expected, let’s put it that way).

If you’re only here because your site is garbled after an upgrade, let me save you some time. There are two reasons (I know of ) for it:

1. You have Clean URLs enabled and your .htaccess file got replaced. That means the RewriteBase rule is now commented out. Don’t bother to turn off Clean URLs, there’s no need to do that. Uncomment it, refresh your site and links should be working properly.
2. If your theme is now messed up and you only see text, plus you can’t navigate around your site, you have your site cache and compression turned on, don’t you? Yeah you do, and now the new version of Drupal doesn’t know how to read the cache files, because it didn’t write them. So do yourself a favor and turn the cache files off. You’ll have to use the “dirty” URLs if you can’t navigate to the admin panel, so instead of example.com/admin you’ll need to type example.com/?q=admin, and so on and so forth. Disable the compression and the cache, and delete all the cache files. Presto-change-o, your site now looks normal again!

So, what can you do to avoid having the same crappy day I did? Let’s take it by the numbers, shall we?

1. Put your site in maintenance mode.

2. Always, always back up your site and your database before doing a core upgrade.

I would recommend doing a backup even before upgrading modules. Don’t rely on backup modules. Do the backups manually, and just so you won’t panic when something goes wrong, test your backup method by restoring from it to a separate install, to make sure you’re doing the right things. This is especially important for database backups, where it’s REALLY important for you to be able to restore from a downloaded SQL file.

Before doing the core upgrade, do a full backup of the entire site, not just the sites folder. And just to make it easier for you to restore the sites folder afterward, do a separate backup of that folder, and of the .htaccess file at the root level of your drupal install. And back up the database, that’s really important! If you do this right, you’ll only need to use the database backup.

3. Turn off all site caching and compression and clear the site cache. This is really important! If you don’t do this, it’s quite likely that your site will be just as garbled as mine after the core upgrade.

4. Create a new site folder on your server, because you’re going to do a brand new install of Drupal (whatever the latest version is). Inside that folder, wget the latest drupal tar.gz file and untar it.

Okay, now comes the fun part.

5. Delete the sites folder in the new Drupal install and copy over your old sites folder.

6. Make sure any changes done to your .htaccess and robots.txt file are reflected in their counterparts in the new Drupal install. Or, it’s quite likely that the old thing that you need to change in the .htaccess file is to uncomment the Rewrite Base line. Find it and uncomment it.

If you don’t uncomment this line and you have Clean URLs enabled, your site will either give you 404 or 500 errors when you try to access the admin interface or alias URLs, so this is quite an important step!

7. Restore your database from the SQL backup. That is, create a new database on your server and through the web interface or through SSH, restore your database backup to it, to get an exact copy of your live Drupal database.

8. Now run the database update script. Browse over to your Drupal install + /update.php and run it to make sure the database upgrade is also completed.

9. Now you have some choices to make. Once you do this, you have two working installs of Drupal: the old, reliable install, which you’ve been using, and the new install, which should be working, but who knows what bugs there might be in the code, that you’ll only discover as you begin working with it.

So now you have two choices: you can either map your domain to the new directory or rename the old directory then rename the new directory to match the old. In other words, you’ll want your domain to point to the new Drupal install. Or, you have the luxury of saying “Forget this new version for now!” and keep using your old Drupal install, until they work out all the bugs (that’ll be the day…)

That’s it! Pat yourself on the back. This should have taken about 15 minutes or less, not a whole day…

I hope this has been helpful!