Jump to content

How to Upgrade Drupal

+ 1
  Angela Byron's Photo
Posted Oct 29 2009 10:16 PM

Once you have Drupal up and running, it's important to keep your site up-to-date. New releases of contributed modules and Drupal core come out periodically to address critical security fixes, and it's important to stay on top of updates as they are released. We'll take a look at Drupal 6's built-in Update Status module, which will notify you of updates available for your site, and we'll talk about the steps required to update both individual modules and the Drupal core itself from one version to another.

Note: You will notice that many people (and even Drupal core's documentation use the terms "updating" and "upgrading" interchangeably. They both refer to replacing existing code with newer code.

Keeping Drupal Up-to-Date

It's not enough to just get Drupal installed; you also need to make sure to keep it up-to-date. New releases of modules and Drupal core come out periodically, most of which fix problems, some of which add new whiz-bang features, and some of which address critical security problems.

Version Numbers

When discussing updates, it helps to have some background information about Drupal's version numbering system. For all the gory details, see http://drupal.org/ha...ok/version-info, summarized in the image below, "Drupal version numbers explained".

Each "major" release of Drupal core gets a new number: Drupal 5, Drupal 6, Drupal 7, and so on. A new major Drupal version is released every 12-18 months, and consists of new features, improved usability, and more flexible APIs. Throughout a major version of Drupal's release cycle, several "minor" versions of Drupal are also released, such as 6.0, 6.1, and 6.2. Minor Drupal versions fix critical security problems and important bugs as well.

Releases of projects like contributed modules, themes, and translations have a version naming scheme such as 6.x-1.3. The "6.x" indicates the major version of Drupal that it is intended to work with; in this case, Drupal 6. The "1" indicates the "major" release of the contributed module. And the "3" indicates that this is the third bug fix release of this major release of the module.

Some releases also have "extra" version information, such as "-beta4" or "-rc2." These indicate that the modules are still in development, but available for testing.

Drupal version numbers explained

Posted Image

Updates between minor versions of Drupal core and modules, such as between Drupal 6.3 to 6.4, or Views module 6.x-2.0 to 6.x-2.1, are normally fairly painless, as long as your site is kept up-to-date. Updates between major versions, however, such as Drupal 6.3 to 7.0, or Organic Groups module 6.x-1.0 to 6.x-2.0, and especially to 7.x-1.0, will need special care, as the changes are generally quite extensive.

On Backward Compatibility

The Drupal project's policy on backward compatibility is that between major versions (such as Drupal 6.x to 7.x), developers are allowed to freely break the underlying code, but must always provide a migration path for a user's data. If a cleaner, faster, or better way of doing something is discovered, developers are allowed (and encouraged) to change the underlying code to work in that fashion. This allows Drupal to stay on the cutting edge of technology without the burden of legacy code that needs to be supported and maintained throughout the ages. However, the result of this policy is that contributed module authors must incorporate these code changes into their own modules between major versions in order to upgrade and stay compatible.

Additionally, the Drupal project currently has a policy of supporting only the current release and one release previous. Although Drupal 6 is the newest release of Drupal as of this writing, both Drupal 6 and Drupal 5 will continue to have bug fixes applied, security updates, and so on. But when Drupal 7 comes out, Drupal 5 will no longer be supported.

As a Drupal user, what these policies mean to you is that there is often a lag time of a few months between when a new major version of Drupal is released and when key contributed modules are ready for widespread use. You should also plan on upgrading your Drupal sites to a new major release every 18-24 months.

For more on Drupal's backward compatibility policy, see http://drupal.org/node/65922.

Update Status Module

Drupal 6 core includes a module called Update Status, which periodically checks Drupal.org for new releases of modules, themes, and Drupal itself. If one or more of these projects are out of date, or if there is a new security release available, a red warning will be displayed on all pages of the administration panel, telling you to head to Administer→Reports→Available updates (admin/reports/updates) for more information. You can also sign up for the security mailing list at http://drupal.org/security and/or follow the Security RSS feed.

The "Available updates" screen, as shown in the image below, "Update status showing the different project statuses", displays an index of projects installed on your website, colored according to status.

Update status showing the different project statuses

Posted Image

The color codes indicate the following status states:

A new recommended version of this project is available, and the version on this website is out of date. Pay special attention to projects marked "Security update required!" and
download the new recommended versions immediately.

Update status was not able to find the state of this project. This will happen on projects such as a specific site's custom, hand-built theme, or on projects that were not downloaded from Drupal.org, or if there was a problem reading the status information for this project.

Project is up-to-date. No further action is required.

Note: The Update Status module can be very noisy if you have many modules installed; over the course of a week, several modules may report that new updates are available if they're undergoing heavy development. You can adjust the notification threshold at Administer→Reports→Available updates on the Settings tab (admin/reports/updates/settings) to email only about security releases, which are mandatory, rather than regular bug fix releases.

Warning: Security updates should be taken very seriously and updated as soon as possible. Read the module's release notes for more information about bug fixes or features that the update offers.

There is also a contributed module called the Upgrade Status module (http://drupal.org/project/upgrade_status), similar to the Update Status module, which will display similar information about enabled modules and whether they have been ported to the next major Drupal version. This functionality comes in handy when determining when might be a good time to move to a new major version, such as from Drupal 6 to Drupal 7.

Site Maintenance Mode

If you navigate to the Administer→Site configuration→Site maintenance (admin/settings/site-maintenance) page, pictured in the image below, "A Drupal website showing in offline mode", you can set the site into "off-line" mode prior to the upgrade taking place. This mode is useful, as sometimes updates can temporarily cause errors before the entire process is completed. Offline mode makes the site inaccessible to regular users while still allowing administrators to work on the site. You don't want users creating content while you are updating the database, because this could lead to losing some data or errors displayed to your site visitors. When you take the site offline, you can also set a message to display to your users to let them know what is going on.

A Drupal website showing in offline mode

Posted Image

Note: If you wish to log in to the site while it is in offline mode, your user account must be assigned to a role that has the "administer site configuration" permission. Pull up the login form by heading to http://www.example.com/user.

The update.php Script

The update.php script, pictured in the image below, "The update.php script, which performs database updates between versions", automatically runs through any underlying
database changes that a module requires in order to move from one version to another. Whether you're updating between minor or major versions of Drupal and contributed modules, update.php is the piece that ensures your data ends up in the places that it should when all is said and done.

The script lists all of the enabled modules on your site, and specifies whether updates are required to be run. A progress bar counts up as each module is updated. And finally, at the end, a report is generated with the database changes that were performed, along with any errors that occurred.

Warning: Because update.php performs updates against the database, it's very important to create a backup of your database before running this script. The Drupal handbook has instructions at http://drupal.org/up...cking-up-the-db.

The update.php script, which performs database updates between versions/

Posted Image

Warning: The update.php script is intended to be run by User 1. If you are not using the User 1 account, you need to edit the settings.php file manually in order to be able to run the update script. You must change the $update_free_access variable in settings.php so that it is equal to TRUE rather than FALSE.

But be careful, if you change this value in settings.php, make sure that you change it back to FALSE as soon as you are done running the update script! Failure to do so means that anonymous users might be able to rerun database updates, which could cause all manner of problems.

Updating Drupal Core

Updating your site often sounds much scarier than the actual experience is. In addition to the included UPGRADE.txt file, the online handbook has a great deal of documentation available and a helpful support forum. The most important step to remember is creating and testing backups of your site.

Warning: It cannot be stressed enough how important backups are when doing upgrades. This holds true for upgrading both Drupal core and contributed modules. You need to make sure you back up both essential parts of a Drupal site: the filesystem and the database. Every system can have a different way to do backups, so that will not be covered in detail. You can ask your system administrator or refer to the backup section of the upgrade guide on Drupal.org. Make sure that you test the backups as well so that you are sure that you can recreate your site if something goes awry.

Updating your out-of-date modules requires manually downloading the necessary files from Drupal.org and placing them on your server just as you did the first time you uploaded them. Drupal does not automatically download updates. This is to prevent overwriting existing module code before you have a chance to test it. For example, it's possible that a module may make a change that requires a newer version of PHP than you have installed, which could result in fatal errors on your site if the files were downloaded blindly. Always test out updated modules on a test server before deploying them on your "live" site.

This section walks you through the steps to update Drupal within a major version to the next minor release number - for example, if you are using Drupal 6.3 and need to upgrade to Drupal 6.4. When upgrading to a new major version of Drupal, such as Drupal 7, the steps are essentially the same, except that you must also upgrade all of your contributed and custom modules and themes at the same time.

  • Get the latest release for your version of Drupal by following the same steps as covered in the section called "Downloading Drupal" section previously.

  • Before you do anything else, you must make backups of both your database and files. Again, refer to your system administrator or the backup guide.

  • Once you have your backups done, log in to your site as User 1.

  • Go to Administer→Site configuration→Site maintenance (admin/settings/site-maintenance) and select the Off-line radio button. Feel free to edit the "Site off-line message" to whatever you choose. Click the "Save configuration" button to take the site offline.

    Note: If you set the site to offline mode and log out before changing it back to online mode, you can still log in easily by going to the user login page manually in the address bar at http://example.com/user.

  • For major version upgrades, it's also recommended to go to Administer→Site building→Themes (admin/build/themes) and switch the site theme to a core theme such as Garland or Bluemarine. This step can prevent errors if underlying things have changed that your site's normal theme depends on.

  • Extract the Drupal files from the tarball and replace all of the existing files on your server with the new files.

  • Make sure that all of your site's files are back in place. Your entire site's contributed and custom code, along with your files directory, should be in the sites folder in your backup. Grab a copy of the sites folder from the backup you made and add it to your Drupal files. If you have made modifications to other system files, such as .htaccess or robots.txt, restore those from backup as well.

  • Now that all of the files are in place, it is time to update the database, too. Go to http://example.com/update.php in your browser. You will be presented with a screen that outlines the steps you should take to update the site. Click the Continue button.

  • You are taken to the update screen. Click the Update button to run the script.

    Note: If you expand the "Select versions" fieldset, you can see which modules have registered that they have update code to be run. Modules that have updates to be run will have a schema version number, such as 6001, preselected in their drop-down select list. Drupal keeps track of this for you, so you shouldn't change this. Modules with no updates will have "No updates available" selected. Even if there are no updates marked, you should still run the update.php script, as it will reset your cache, making sure that Drupal recognizes all of the new files. Failing to run the script may cause some weirdness in the newly updated site until the cache is cleared at Administer→Site configuration→Performance (admin/settings/performance).

  • After the script runs, you will be returned to a screen indicating that the update is complete. If you changed to a core theme for the upgrade, switch it back to your regular theme at Administer→Site building→Themes (admin/build/themes).

  • Click around your site and verify that the update was successful. Once you are convinced the site looks OK, return to Administer→Site configuration→Site maintenance (admin/settings/site-maintenance), select the Online radio button, and click "Save configuration" to take the site back online.

Updating Contributed Modules

Drupal's contributed projects tend to move more quickly than Drupal core and therefore require more updates within a Drupal version's life cycle. You can upgrade multiple modules at the same time, although it's best to do one at a time to reduce the chance of errors, and to allow you to isolate problems that might come up during an upgrade.

To update contributed modules, follow these steps. You will see that the process is the same as the one used for Drupal core, only the files that are changed are a little different.

  • Just as with Drupal core, you need to get the latest version of the module you wish to update. You should always read any release notes that are associated with the module to make sure that there are no special instructions for your update.

  • It is still important to make backups of your entire Drupal installation, even though you are only updating a module. If something goes wrong you want to be able to restore the site to the state it was in before you began. So make your backups before proceeding.

  • Log in to your site as User 1.

  • Go to Administer→Site configuration→Site maintenance (admin/settings/site-maintenance) and select the Off-line radio button. Edit the "Site off-line message" to whatever you choose. Click "Save configuration" to take the site off-line.

  • Now it's time to replace the module files. Extract the module file that you downloaded from Drupal.org and completely replace the old module. To be thorough, you can delete the entire folder for the old module and then add the new, fresh module folder to the sites/all/modules directory.

  • Go to http://example.com/update.php in your browser and click the Continue button.

  • Click the Update button to actually run the update script.

  • Return to your site and make sure that everything looks okay. You should especially check the functionality that the particular module or modules provided for your site and make sure that there are no errors.

  • Repeat steps 5 through 8 for each module that you wish to update.

  • To finish up, go back to Administer→Site configuration→Site maintenance (admin/settings/site-maintenance), select the Online radio button, and click "Save configuration" to take the site back online.

Using Drupal

Learn more about this topic from Using Drupal.

With the recipes in this book, you can take full advantage of the vast collection of community-contributed modules that make the Drupal web framework useful and unique. You'll get the information you need about how to combine modules in interesting ways (with a minimum of code-wrangling) to develop a variety of community-driven websites -- including a wiki, publishing workflow site, photo gallery, product review site, online store, user group site, and more.

See what you'll learn

0 Subscribe

0 Replies