Chris@0: /**
Chris@0:  * Implements hook_update_N().
Chris@0:  */
Chris@0: function {{ machine_name }}_update_N(&$sandbox) {
Chris@0:   // For non-multipass updates, the signature can simply be;
Chris@0:   // function {{ machine_name }}_update_N() {
Chris@0: 
Chris@0:   // For most updates, the following is sufficient.
Chris@0:   db_add_field('mytable1', 'newcol', array('type' => 'int', 'not null' => TRUE, 'description' => 'My new integer column.'));
Chris@0: 
Chris@0:   // However, for more complex operations that may take a long time,
Chris@0:   // you may hook into Batch API as in the following example.
Chris@0: 
Chris@0:   // Update 3 users at a time to have an exclamation point after their names.
Chris@0:   // (They're really happy that we can do batch API in this hook!)
Chris@0:   if (!isset($sandbox['progress'])) {
Chris@0:     $sandbox['progress'] = 0;
Chris@0:     $sandbox['current_uid'] = 0;
Chris@0:     // We'll -1 to disregard the uid 0...
Chris@0:     $sandbox['max'] = db_query('SELECT COUNT(DISTINCT uid) FROM {users}')->fetchField() - 1;
Chris@0:   }
Chris@0: 
Chris@0:   $users = db_select('users', 'u')
Chris@0:     ->fields('u', array('uid', 'name'))
Chris@0:     ->condition('uid', $sandbox['current_uid'], '>')
Chris@0:     ->range(0, 3)
Chris@0:     ->orderBy('uid', 'ASC')
Chris@0:     ->execute();
Chris@0: 
Chris@0:   foreach ($users as $user) {
Chris@0:     $user->name .= '!';
Chris@0:     db_update('users')
Chris@0:       ->fields(array('name' => $user->name))
Chris@0:       ->condition('uid', $user->uid)
Chris@0:       ->execute();
Chris@0: 
Chris@0:     $sandbox['progress']++;
Chris@0:     $sandbox['current_uid'] = $user->uid;
Chris@0:   }
Chris@0: 
Chris@0:   $sandbox['#finished'] = empty($sandbox['max']) ? 1 : ($sandbox['progress'] / $sandbox['max']);
Chris@0: 
Chris@0:   // To display a message to the user when the update is completed, return it.
Chris@0:   // If you do not want to display a completion message, simply return nothing.
Chris@0:   return t('The update did what it was supposed to do.');
Chris@0: 
Chris@0:   // In case of an error, simply throw an exception with an error message.
Chris@0:   throw new DrupalUpdateException('Something went wrong; here is what you should do.');
Chris@0: }