function hook_update_N

Perform a single update.

For each patch which requires a database change add a new hook_update_N() which will be called by update.php. The database updates are numbered sequentially according to the version of Drupal you are compatible with.

Schema updates should adhere to the Schema API: http://drupal.org/node/150215

Database updates consist of 3 parts:

• 1 digit for Drupal core compatibility
• 1 digit for your module's major release version (e.g. is this the 5.x-1.* (1) or 5.x-2.* (2) series of your module?)
• 2 digits for sequential counting starting with 00

The 2nd digit should be 0 for initial porting of your module to a new Drupal core API.

Examples:

• mymodule_update_5200()
  • This is the first update to get the database ready to run mymodule 5.x-2.*.
• mymodule_update_6000()
  • This is the required update for mymodule to run with Drupal core API 6.x.
• mymodule_update_6100()
  • This is the first update to get the database ready to run mymodule 6.x-1.*.
• mymodule_update_6200()
  • This is the first update to get the database ready to run mymodule 6.x-2.*. Users can directly update from 5.x-2.* to 6.x-2.* and they get all 60XX and 62XX updates, but not 61XX updates, because those reside in the 6.x-1.x branch only.

A good rule of thumb is to remove updates older than two major releases of Drupal. See hook_update_last_removed() to notify Drupal about the removals.

Never renumber update functions.

Further information about releases and release numbers:

• http://drupal.org/handbook/version-info
• http://drupal.org/node/93999 (Overview of contributions branches and tags)
• http://drupal.org/handbook/cvs/releases

Implementations of this hook should be placed in a mymodule.install file in the same directory as mymodule.module. Drupal core's updates are implemented using the system module as a name and stored in database/updates.inc.

If your update task is potentially time-consuming, you'll need to implement a multipass update to avoid PHP timeouts. Multipass updates use the $sandbox parameter provided by the batch API (normally, $context['sandbox']) to store information between successive calls, and the $sandbox['#finished'] value to provide feedback regarding completion level.

See the batch operations page for more information on how to use the batch API: http://drupal.org/node/180528

Parameters

$sandbox: Stores information for multipass updates. See above for more information.

Return value

An array with the results of the calls to update_sql(). An update function can force the current and all later updates for this module to abort by returning a $ret array with an element like: $ret['#abort'] = array('success' => FALSE, 'query' => 'What went wrong'); The schema version will not be updated in this case, and all the aborted updates will continue to appear on update.php as updates that have not yet been run. Multipass update functions will also want to pass back the $ret['#finished'] variable to inform the batch API of progress.

Related topics

File

developer/hooks/install.php, line 271

Documentation for the installation and update system.

Code

function hook_update_N(&$sandbox) {
  // For non-multipass updates, the signature can simply be;
  // function hook_update_N() {

  // For most updates, the following is sufficient.
  $ret = array();
  db_add_field($ret, 'mytable1', 'newcol', array('type' => 'int', 'not null' => TRUE));
  return $ret;

  // However, for more complex operations that may take a long time,
  // you may hook into Batch API as in the following example.
  $ret = array();

  // Update 3 users at a time to have an exclamation point after their names.
  // (They're really happy that we can do batch API in this hook!)
  if (!isset($sandbox['progress'])) {
    $sandbox['progress'] = 0;
    $sandbox['current_uid'] = 0;
    // We'll -1 to disregard the uid 0...
    $sandbox['max'] = db_result(db_query('SELECT COUNT(DISTINCT uid) FROM {users}')) - 1;
  }

  $users = db_query_range("SELECT uid, name FROM {users} WHERE uid > %d ORDER BY uid ASC", $sandbox['current_uid'], 0, 3);
  while ($user = db_fetch_object($users)) {
    $user->name .= '!';
    $ret[] = update_sql("UPDATE {users} SET name = '$user->name' WHERE uid = $user->uid");

    $sandbox['progress']++;
    $sandbox['current_uid'] = $user->uid;
  }

  $ret['#finished'] = empty($sandbox['max']) ? 1 : ($sandbox['progress'] / $sandbox['max']);

  return $ret;
}