Home ยป API reference

hook_update_N

Definition

hook_update_N(&$sandbox = NULL)
docs/docs/developer/hooks/install.php, line 256

Description

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:

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.

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

Namesort iconDescription
HooksAllow modules to interact with the Drupal core.

Code

<?php
function hook_update_N(&$sandbox = NULL) {
  // 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;
}
?>