DrupalUpdateException|PDOException In case of error, update hooks should throw an instance of DrupalUpdateException with a meaningful message for the user. If a database query fails for whatever reason, it will throw a PDOException.
Perform a single update.
For each change that requires one or more actions to be performed when updating a site, add a new hook_update_N(), which will be called by update.php. The documentation block preceding this function is stripped of newlines and used as the description for the update on the pending updates task list. Schema updates should adhere to the Schema API.
Implementations of hook_update_N() are named (module name)_update_(number). The numbers are composed of three parts:
- 1 digit for Drupal core compatibility.
- 1 digit for your module's major release version (e.g., is this the 7.x-1.* (1) or 7.x-2.* (2) series of your module?). This digit should be 0 for initial porting of your module to a new Drupal core API.
- 2 digits for sequential counting, starting with 00.
- mymodule_update_7000(): This is the required update for mymodule to run with Drupal core API 7.x when upgrading from Drupal core API 6.x.
- mymodule_update_7100(): This is the first update to get the database ready to run mymodule 7.x-1.*.
- mymodule_update_7200(): This is the first update to get the database ready to run mymodule 7.x-2.*. Users can directly update from 6.x-2.* to 7.x-2.* and they get all 70xx and 72xx updates, but not 71xx updates, because those reside in the 7.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. For further information about releases and release numbers see: Maintaining a drupal.org project with Git
Never renumber update functions.
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.
Not all module functions are available from within a hook_update_N() function. In order to call a function from your mymodule.module or an include file, you need to explicitly load that file first.
During database updates the schema of any module could be out of date. For this reason, caution is needed when using any API function within an update function - particularly CRUD functions, functions that depend on the schema (for example by using drupal_write_record()), and any functions that invoke hooks. See @link update_api Update versions of API functions @endlink for details.
The $sandbox parameter should be used when a multipass update is needed, in circumstances where running the whole update at once could cause PHP to timeout. Each pass is run in a way that avoids PHP timeouts, provided each pass remains under the timeout limit. To signify that an update requires at least one more pass, set $sandbox['#finished'] to a number less than 1 (you need to do this each pass). The value of $sandbox['#finished'] will be unset between passes but all other data in $sandbox will be preserved. The system will stop iterating this update when $sandbox['#finished'] is left unset or set to a number higher than 1. It is recommended that $sandbox['#finished'] is initially set to 0, and then updated each pass to a number between 0 and 1 that represents the overall % completed for this update, finishing with 1.
See the @link batch Batch operations topic @endlink for more information on how to use the Batch API.