Managing Drupal site updates with hook_update_N()

One of the often discussed topics in the Drupal community is the site deployment process, and best practices for managing development, staging, and production environments. In this post, I am going to explain part of our approach for a particular project and how hook_update_N() made our lives a bit easier.

Background

One of the projects we recently completed for a client involved creating a Drupal distribution that could be used to deploy many similar sites. The distribution consists of a drush make file, an install profile, six Features, another half dozen custom modules, and many contrib modules. We use the Aegir hosting system to manage site deployments.

Platform deployments

Aegir uses the concept of Platforms to organize deployments of sites. mig5 has written a very nice post about this so, if you are interested to learn more about this, read mig5's write-up on deployments with Aegir. The gist of working with Aegir is that you create a Platform which contains the codebase for your site, then you create a new Site in Aegir which is an instance of that Platform.

In our case, we have a Platform that 10 sites use as their common codebase. When a new version of Drupal core, or security updates for contrib modules are released, we can simply run the command drush make ourdistro.build. This will grab the contrib modules, install profile, and custom code that we have in our SVN repository and create a new Platform. We then tell Aegir that the Platform exists, and migrate our sites to it.

Making changes to live sites

All this works fine when you are creating new Sites based on a new Platform. But what happens when you want to update some settings across all the live sites?

We could login in to each site and make the settings changes we wanted manually. But in addition to being a tedious process, it is also error-prone and not sustainable or scalable.

Using Features for updates

Another option is to use Features to manage updates to sites.

One of the Features in our distribution is a core Feature called ourdistro_core which contains a number of settings, variables, and configuration that should not change across sites.

The ourdistro_core Feature contained some permissions settings related to viewing user profiles. Originally, anonymous users and authenticated users had permissions to access user profiles. We had to change this to allow only the “administrator” role to access profiles.

The first thing we had to do was update the ourdistro_core Feature to take this change into account. Easy enough. Then we built a new Platform. New sites built on that Platform have the new settings in place, great! But what happens when we migrate an existing site on an earlier version of the platform to the new one? The changes won’t take effect, because the Feature will be overridden.

This is actually one of the best parts of Features. You can update your Feature code and push it to a site, but the changes won’t take effect immediately. Rather, you can see which parts are overridden and can optionally decide which components to revert. This is a good thing.

Our problem was that ourdistro_core had some permissions that had been modified on various sites that we did not want to revert. For example, ourdistro_core Feature included permission settings for "posting comments without approval" that had been overridden on a number of sites. If we wanted to revert the permissions in the Feature to take our new changes into account, we would lose all other customizations for the permissions.

(As a side note: one of the lessons learned from this project is that it is really important to keep your Features manageable and discreet pieces of functionality, for exactly this reason. Kit is helpful in defining the scope of a Feature. If a Feature becomes too large, updates or feature changes become difficult. If you use the same Feature across 10 sites, the problem becomes 10 times worse.)

Using hook_update_N() to update the database

The solution is to include an implementation of hook_update_N() in the ourdistro_core Feature that will update the settings for us. When we migrate a Site to a new Platform, hook_update_N() will be invoked in the ourdistro_core Feature, which will take care of making the necessary database changes for us.

Here's how we did it:

Revoke “access user profiles” permissions for some user roles

This example uses the excellent Permissions API module

Here are some more examples:

Changing the WYSIWYG Editor from TinyMCE to CKEditor

Provide a default backup schedule for each site

And so on.

Conclusions

Whether you are managing a single site or a grouping of sites, hook_update_N() is invaluable in the deployment process. There are many great examples out there, so have a look and start using it, it is well worth the time and effort to learn.