C H A P T E R  7

Updating Drupal

by Benjamin Melançon

“Another flaw in the human character is that everybody wants to build and nobody wants to do maintenance.”

—Kurt Vonnegut, Jr.

Updating Drupal 7 means staying within Drupal 7. This is known as a minor version update. In Drupal core, the version numbers for a minor update such as the second and third updates to the Drupal 7 release look like 7.2 to 7.3. In contributed modules, version numbers for minor updates such as the eleventh and twelfth updates to the second version of a module for Drupal 7 look like 7.x-2.11 to 7.x-2.12. (Drupal version numbers do not have leading zeros, which can be confusing. Remember that the order is 7.1, 7.2, ... 7.8, 7.9, 7.10, 7.11.)

There is a very large difference between a minor version update and a major version upgrade. A major version upgrade such as Drupal 6 to Drupal 7 will require replacing all your modules with versions compatible with Drupal 7 core; your custom theme and custom code will need changes; and it will take a lot of work to get a complex site working well again. You don't have to worry about any of that in this chapter. When updating Drupal core from 7-point-something to 7-point-something-higher, nothing is supposed to break in the API. All the modules and the theme should continue to work, and nothing should need to be reconfigured. If you need to upgrade a Drupal 6 site to Drupal 7, Appendix A will get you started with that.

Why Update

Keeping Drupal core current, then, is easy. It's also very important. Primarily, it's critical for the security of your web site. Secondarily, bug fixes and other improvements will make it into the current release.

Drupal's security record, by the way, is excellent. As a rule, security vulnerabilities in Drupal are uncovered first by the security team (drupal.org/security-team) or other friendly Drupalistas—not fixed after they have been exploited by hostile parties. Once a security vulnerability has been identified and a release of Drupal made, however, it's easy for anyone with ill intentions to read the security advisory and take advantage of that vulnerability. This is why you must keep your site current.

It's worth noting that most of the security vulnerabilities fixed during the course of a Drupal release are unlikely to matter for a well-configured site; to exploit the vulnerability, you must give less-trusted users generous permissions. Chapter 6 covered Drupal's excellent security and other ways to make your web site secure.

New versions of Drupal 7 core, the minor version updates, will be released for as long as the community supports Drupal 7 (which, officially, is until Drupal 9 comes out).

This chapter covers three approaches to updating core between minor version updates. First, you'll look at the manual update process described in Drupal core itself. Next, you'll look at the Drush command to update Drupal core. Last and perhaps least, you'll look at my preferred method of creating a diff via a shell script and applying it as a patch. This latter approach works best if you have a known modification to Drupal core that you wish to preserve (which does not necessarily mean you have hacked core; the .htaccess file, for instance, can legitimately be changed). The first approach is necessary if there are known or unknown modifications to core you need to be sure are removed and is, in general, the surest approach.

The following preparation steps apply no matter which approach you take to update Drupal core.

Preparation

Whenever you touch Drupal's code, there's the potential for something to go wrong. So even a minor-point–release update, as described here, should be:

• Tested offline and/or on a development server first.
• Scheduled to go live at a time when your site will be less heavily used.

Check the release announcements. If anything unusual is needed during the update process, it will be noted here. Are you updating through more than one minor release (for instance 7.0 to 7.3) at once? Check all the release announcements. Go to drupal.org's Download & Extend Drupal core (drupal.org/project/drupal) and click on the “View all releases” link at the bottom (or go directly to drupal.org/node/3060/release).

Make sure everything in your version control is committed. If using Git, type git status while within a directory in your Drupal project. (And if you're working with others, make sure you git pull first.)

Back up your database immediately before the update, in addition to your regular nightly (or more frequent) backups. You can use a web graphical interface such as the one provided by phpMyAdmin or you can use Drush or the following command line:

Manual Update

This approach follows the UPGRADE.txt recommendations included in every copy of Drupal core. It is, then, the officially recommended way of updating Drupal from one minor version to another. It's not the easiest way, and so for something that must be as regular and automatic as you can make it, not the best way. But it's important to know it as a failsafe way.

All Drupalistas soon learnthe rule Don't hack core. In general, you're not supposed to touch anything in your Drupal installation outside the sites directory. There are two files in Drupal core, however, that you won't be chastised for changing: .htaccess and robots.txt. You might not need to touch them, but modifying them is not considered hacking core. As these files live outside the sites folder (which you will preserve in its entirety, described shortly), they require special attention to preserve any changes you have made.

The final preparatory step for the manual update is to download the latest release of your version of Drupal via the following code (note that this code is for version 7.1; you will want the latest release):

Follow the Steps in UPGRADE.txt

These instructions follow the steps from UPGRADE.txt but I've changed them a little bit in certain cases, mostly because some of the work has been covered in the “Preparation” section.

1. Log in as a user with the permission “Administer software updates” (the first user created, also referred to as user 1, always works).
2. Go to Administration Configuration Development Maintenance mode (admin/config/development/maintenance). Checkmark the “Put site into maintenance mode” checkbox and press Save configuration at the bottom of the page. (You can put something personal and reassuring for your visitors as the “Maintenance mode message” since they will see that instead of your site.)
3. Copy all changed files out of your codebase. This should be the entire sites directory and possibly .htaccess and robots.txt. If you don't know if anything's changed in these files, copy them out; you can use the diff command to compare files later. Also, move out any other files you added or have changed outside of sites. I recommend copying everything. Then delete the entire codebase, and copy only the sites directory back in and optionally other changed files such as .htaccess and robots.txt.

   This is accomplished in the command line steps below by moving and then copying the desired files back in. In this example, the Drupal directory was example/web.

   mv example/web examplewebtmp/
mkdir -p example/web
cp -pr examplewebtmp/sites/ example/web/
cp examplewebtmp/.htaccess example/web/
cp examplewebtmp/robots.txt example/web/
4. Copy the latest Drupal release into the codebase directory that is empty except for sites and other modified files. Don't overwrite anything in the sites directory.

   This command line step copies a new Drupal into its install directory around sites and other files you have put there (files are not overwritten):

   cp -R drupal-7.1/* drupal-7.1/.htaccess example/web/
rm example/web/sites/default/default.settings.php
5. Re-apply any modifications to files such as.htaccess and robots.txt.

   If the release notes indicate changes to settings.php, make these changes. If you've made changes to .htaccess and robots.txt, reapply them. If you're not sure what exactly has changed in any of these, use a comparison tool such as diff. Compare the new version of .htaccess to your old one that you moved back in; do the same for robots.txt. For settings.php, compare it with the new default.settings.php that's replaced your old default.settings.php.

   You can use a graphical diff tool or these command lines to see changes between files:

   diff -up example/websites/default/settings.php/
example/web/sites/default/default.settings.php

diff -up example/web/robots.txt drupal-7.1/robots.txt

diff -up example/web/.htaccess example/web/.htaccess

   The first diff shows what has changed in the new recommendations for a settings.php file. The second and third diffs compare the new, core robots.txt and .htaccess files with your old, possibly modified versions. Evaluate what you see with + signs in front as things you may want to add or add back, and things with - signs in front as things you may want to remove— but most of these will be changes you yourself made.

   Tip If you don't know if core in the Drupal version you're dealing with has been hacked, and you know precisely what version of Drupal you are using, you can download a pure copy of it and diff between it and your copy to see what modifications, if any, have been made. See the “Diff Update” section for the commands.

6. Go to update.php, such as http://example.localhost/update.php on a local test site and http://example.com/update.php on a live site. Although this is not necessary if the point release (or releases) you are updating have not had any database changes, this information is not yet noted specially in the release notes. Go to update.php to check. Click continue; if it doesn't have to be run, it will tell you “No pending updates”, as shown in Figure 7-1. If there are updates, run them.
   

   Figure 7-1. No pending updates

7. Go to Administration Reports Status report (admin/reports/status) to see if Drupal has problems with anything. Visit all your key pages to test key functionality and also check Drupal's watchdog log (at admin/reports/dblog if using Database logging module or in your operating system's syslog if using the Syslog module).
8. This step (Step 8 from UPGRADE.txt) only applies if you couldn't log in and had to set $update_free_access to TRUE in settings.php; you probably won't have needed to do this.
9. Go back to Administration Configuration Development Maintenance mode (admin/config/development/maintenance). Uncheck “Put site into maintenance mode” and Save configuration.

Now Do It Live

If all goes well, commit your code changes, perform steps 1 and 2 on your production site (or better, first on a staging site), deploy the updated code to your live site, and repeat steps 6 through 10 on your live site. See Chapter 13 for deployment recommendations.

Drush Update

With Drush, the process is a lot easier. It first takes care of all contributed modules that need updating. The command for this is drush pm-update, or simply drush up.

Remember to always try this first on a copy of your site and database before trying it on a production site. Instead of the previous command, which combines code and database updates, you can use drush upc to update only code, which you can commit to your repository. With drush updatedb (for updating the database)tested successfully on a test site, you can deploy the code to a live site and immediately run drush updated there (or visit update.php).

Contributed module updates are discussed in a later section. To update only Drupal core with Drush, use the command drush up drupal.

As for most things Drush, see Chapter 26for more complete coverage.

Diff Update

Now we come to the method that I personally use. It can be made a Drush script, I believe, but I haven't managed to do it yet, to my shame. So I leave it as an exercise for the reader!

Listing 7-1 is a script for downloading a fresh copy of the latest Drupal version and your current Drupal version, and applying the difference. This means that in many cases, none of your changes to Drupal will conflict with the changes that are simply re-applied over your existing code.

It should also be possible to generate this diff directly from git.drupal.org, which would be a more efficient and refined improvement than this script, but the same in effect. This improvement might be made to this script, which is another reason to downloadit from dgd7.org/update; don't try to type it in! The commands for using the script are following Listing 7-1.

To use the script, you need to provide the path to your Drupal site. I apologize for naming this script “upgrade,” although it could possibly be used to start major version upgrades, too.

If the script is in your home directory scripts, and the site at hand is ‘dgd7' in the code directory within your home directory, with the Drupal installation in web, this command will work when run from anywhere:

Contributed Modules

It is also vital to keep your contributed modules current. The report page provided by update.module, Administration Reports Available updates (admin/reports/updates), will give you a list of ones that need updating. Modules are really updated not by the module, but by the project; some projects contain more than one module, and the update page indicates the modules contained in each project with the “Includes” line, as shown in Figure 7-2.

Figure 7-2. Contributed modules shown in the available updates report, with links for download and release notes of modules with updates available

The manual way to update contributed modules is to delete each out-of-date module and untar a freshly downloaded latest stable release one in its place. Then go to update.php for your site, such as http://example.localhost/update.php for your test and http://example.com/update.php for your live site. There's really no reason to recommend the manual download approach over the automated options, which are described below.

No matter how you update, first test the results thoroughly on a copy of your production site. As with core, always perform contributed module updates first on a local or test copy of your live site. Much more than with core, you have to check carefully that contributed modules have not changed their behavior when you update them. See Chapter 13 on deployment or Chapter 26 on Drush for automated approaches to bringing copies of your live database onto a local or testing environment.

There are two easy, automated way to do the updates. (Neither of them, however, get you out of testing the update before applying it to your live site.)

Drupal's Automated Module Installer

To automatically update the modules that need updating, visit Administration Reports Available updates Update (admin/reports/updates/update) on your Drupal site. Checkmark the modules you want to update and press the “Download these updates” button at the bottom of the form, as shown in Figure 7-3.

Figure 7-3. The automated update page with an example of a no-longer-supported branch of a module and two modules needing simple minor-point updates

It's best to apply one or a limited number of related updates at a time, especially any with a major version upgrade warning, so that you can more easily identify the cause of any changes you notice in testing. After Drupal automatically places the code for you, don't forget to run the database updates (after you try, Drupal will tell you if none are necessary, as shown in Figure 7-1).

You can run Drupal's automated contributed module updater locally, and then commit the code to bring the changes to live. This allows you to continue to follow best practice of not changing code on the live server.

If Drupal's update manager module can't run the upgrade for you through the user interface (if it asks you for FTP information you are not sure you have), don't bother trying to make it work. That time would be much better invested making Drush work instead.

Updating Modules with Drush

The Drush commands for updating contributed modules are, as mentioned, exactly the same as for Drupal core. By default, Drush will try to do all at once: first all the contributed modules, and then Drupal core.

For installing Drush, see Chapter 2. For much more about Drush and the great things you can do with it, see Chapter 26.

At the time of this writing, there is a (long) issue (drupal.org/node/1002658) about making sure Drush checks for all available updates and somehow not take a minute or two looking them up (the behavior in the current patch). Drush will also sometimes claim that it failed in an update (because of an unavailable release or some other minor failure) and was unable to recover from its backups. In fact, Drush almost certainly succeeded in updating the code; you don't have to manually roll anything back and can instead run database updates, commit the code, and deploy and run database updates on stage and production sites. To avoid some of these issues, and as a matter of best practice for testing and identifying what caused (or solved) a problem, you can have Drush update one or a few projects at a time, such as updating only CTools and Views project code with drush upc ctools views.

To choose modules to update when using Drush, look at Administration Reports Available updates (admin/reports/updates) to decide what you want to update and hover over the download link to see what project name you should give Drush. (You can also run drush up to see what updates are available and cancel (n) before updating anything, so as to pick and choose one to run at a time.) From the previous example, the LoginToboggan module's download link is ftp.drupal.org/files/projects/logintoboggan-7.x-1.2.tar.gz which means the command you want to use to download it is

Not all projects have nearly identical human-facing and system-facing names. Image resize filter is image_resize_filter and Meta tags is nodewords. If there are several possible versions to update to (such as when there's a new major version upgrade available), you can include the version you want, also in the form seen in the download link, like so:

Summary

This chapter has served at least two purposes. It showed you several ways to keep your Drupal sites current, so just pick one and do it! It also showed that there are always multiple ways to do things within and around Drupal.