April 03, 2009

Using Drupal Module Install Scripts to Simplify Site Deployments

Del.icio.us   Technorati   Digg   StumbleUpon

One of the best features in Drupal is the ability to configure Drupal from within the Web UI. While this allows quick manipulation from the front end, regardless of technical expertise, it can quickly become a nightmare when migrating modified data between local, development, test, and production servers. Going through the process of updating all of these settings manually during each deployment is not only time consuming but extremely error prone, especially if you have multiple developers working simultaneously on separate machines.

Luckily, Drupal provides functionality to create module install scripts to make much of this process automated and repeatable. At first, it may seem like you're spending a lot of time writing these update scripts but, trust me, the time is well spent. You will save significantly more time and frustration when it comes time to deploy these changes.

Using install scripts can also improve your Q/A process. With the scripts in place you can load up a production database at any time and quickly run the updates to ensure that everything will run smoothly when you actually deploy to the live site. Install scripts also allow you to revert your database easily if anything should go wrong. Once you write he scripts, you don't have to think about database updates, all you need to do is point your browser to update.php and Drupal handles the rest for you!

Creating .install Files
To create an install file for your module simply create a file named module_name.install and put it in the same directory as module_name.module (along with the module_name.info file). In this file you can define functions that are triggered when a module is installed, uninstalled, enabled, disabled, or updated.

Hooks Available To .install Files

• hook_install() - This hook is called once when
  the module is first enabled
• hook_uninstall() - This hook is called when the
  module is uninstalled
• hook_enable() - This hook is called every time
  the module is enabled
• hook_disable() - This hook is called every time
  the module is disabled
• hook_requirements() - This hook allows you to
  define specific requirements that must be met before the module can be
  installed
• hook_schema() - This hook is new in Drupal 6 and
  is used to define new database tables and fields using the schema API.
  More information on the Schema API can be found here.
• hook_update_n() - Used to create and run database updates
  as your application grows. These functions are called by running
  update.php. The n in the function name can be any unique number though
  most modules use a four digit code as described here. These functions are called alphabetically
  by the module name then numerically by the version number. The current
  module version is tracked in the system table.

This sample file on the Drupal API site is a good source for .install file functionality.

Enabling / Disabling Modules
Install scripts are a perfect place for automatically enabling or disabling modules. By keeping this functionality in update functions you avoid visiting the module page every time you add a new module. Here's how to do it:

Enable Modules

Disable Modules

If you are enabling new modules run update.php a second time to ensure that all the appropriate update scripts are run.

Setting System Variables
Nearly all of Drupal's module configuration options are stored in Drupal variables. This includes everything from the site name to email templates. Most custom modules also utilize these variables to store user configurable settings. To see all the currently stored variables take a look at the variables database table.

To programmatically set a variable, simply call variable_set(). This function accepts two arguments: name and value. The value argument can be either a string or array which will be automatically serialized for storage and unserialized when variable_get() is called. You can use this function to set new variables or modify existing ones.

Here are some examples:

Custom SQL statements
Occasionally you'll need to run updates that the standard Drupal API can't handle. This is no problem. You can put anything you want in update scripts including custom SQL statements. Drupal provides a special database query function called update_sql() to handle update queries. If I wanted to publish all previously unpublished story nodes, I could add the following update function to my install file:

update_sql() will return a status message that will print on the update confirmation page indicating if it was successful or not. Please note, update_sql() does not accept additional arguments in a sprintf format like db_query(). All arguments should go directly in the SQL statement, like so:

update_sql() can accept any valid SQL statement.

Using Devel Macro To Manipulate CCK Fields
While it's easy to define a content types from within modules, you unfortunately can't do the same with CCK groups and fields. Currently, you have to write complicated update scripts to achieve this. This will change when the Field API is released (finally!) with Drupal 7, but for right now the Devel Macro module will automate much of this scripting for you.

For those unfamiliar with the Devel Macro module, it's a module that can record and playback Drupal form submissions. This is extremely useful when you need to run an update on something that doesn't have a solid API or requires an enormous amount of coding that can more easily be handled in a few form submissions. CCK certainly falls into this category.

Using the Devel Macro module is pretty straightforward. You begin recording, make your modifications via standard Drupal form submissions, and finally export the macro array. This macro array can then be placed in an update function.

If I wanted to add a new CCK field I would do the following:

• Start recording form submissions with the Devel Macro module
• Add the field using the standard CCK UI
• Stop recording and export the macro
• Paste your macro into an install script

Here's an example of an update script that uses a Devel Macro script to create a new CCK field:

Best Practices For Running Devel Macro Imports From Update Scripts:

• Make sure you include all necessary files prior to running the macro (including macro.module) to avoid errors if the module is not enabled (Devel should never be enabled on the production site)
• Update you development database with a production database before you record any macros. I've found this is more reliable and will help avoid future headaches with duplicate key errors
• Keep you macros short. Don't string too many form submissions in a row.

Setting Permissions
There is currently no API methods to add or remove permissions in Drupal. Fortunately the useful Permission API module to simplifies this. With this module installed you'll be able to easily add or revoke permissions for your roles in your update scripts. For example:

I would argue that Drupal deployments should involve little to no manual interaction for database changes. It's just too risky and time consuming. Budgeting the extra time up-front to write thorough install scripts is a major step in achieving this. It can be the difference of a full days effort to deploy to the staging and production environments to literally a few minutes for each build.

While install scripts can automate most database changes, it's not the only method available to you in Drupal. My next post will explain how to use standard hooks to define things like views, blocks, menu callbacks, and validation all from code in your modules. Defining these items in code instead of the database will further alleviate any manual action when deploying changes.

Posted at 11:35 am by Jeff Rigby

Technorati Tags: Array

Del.icio.us   Technorati   Digg   StumbleUpon

Add comment

• Presentation on Scaling Drupal in the Enterprise 11/05/2009 - 11:33
• Automating Drupal Site Rebuilds With Drush 10/05/2009 - 12:38
• Potential SVN Security Risk 09/25/2009 - 19:31
• Sacrificing Aesthetics for Site Performance and Improved Search Ranking 02/25/2008 - 04:20

Contact DPCI to learn more about our Web content management systems,
digital asset management solutions, online collaboration software, custom development, multi-channel publishing systems, and workflow management solutions.