function hook_update_N

hook_update_N(&$sandbox)

Perform a single update between minor versions.

hook_update_N() can only be used to update between minor versions of a module. To upgrade between major versions of Drupal (for example, between Drupal 7 and 8), use the Migrate API instead.

Naming and documenting your function

For each change in a module that requires one or more actions to be performed when updating a site, add a new implementation of hook_update_N() to your mymodule.install file (assuming mymodule is the machine name of your module). Implementations of hook_update_N() are named (module name)_update_(number). The numbers are normally composed of three parts:

• 1 or 2 digits for Drupal core compatibility (Drupal 8, 9, 10, etc.). This convention must be followed.
• 1 digit for your module's major release version; for example, for 8.x-1.* use 1, for 8.x-2.* use 2, for Core 8.0.x use 0, and for Core 8.1.x use 1. This convention is optional but suggested for clarity.
• 2 digits for sequential counting, starting with 01. Note that the x000 number can never be used: the lowest update number that will be recognized and run for major version x is x001.

Examples:

• node_update_8001(): The first update for the Drupal 8.0.x version of the Drupal Core node module.
• mymodule_update_8101(): The first update for your custom or contributed module's 8.x-1.x versions.
• mymodule_update_8201(): The first update for the 8.x-2.x versions.

Never renumber update functions. The numeric part of the hook implementation function is stored in the database to keep track of which updates have run, so it is important to maintain this information consistently.

The documentation block preceding this function is stripped of newlines and used as the description for the update on the pending updates task list, which users will see when they run the update.php script.

Notes about the function body

Writing hook_update_N() functions is tricky. There are several reasons why this is the case:

• You do not know when updates will be run: someone could be keeping up with every update and run them when the database and code are in the same state as when you wrote your update function, or they could have waited until a few more updates have come out, and run several at the same time.
• You do not know the state of other modules' updates either.
• Other modules can use hook_update_dependencies() to run updates between your module's updates, so you also cannot count on your functions running right after one another.
• You do not know what environment your update will run in (which modules are installed, whether certain hooks are implemented or not, whether services are overridden, etc.).

Because of these reasons, you'll need to use care in writing your update function. Some things to think about:

• Never assume that the database schema is the same when the update will run as it is when you wrote the update function. So, when updating a database table or field, put the schema information you want to update to directly into your function instead of calling your hook_schema() function to retrieve it (this is one case where the right thing to do is copy and paste the code).
• Never assume that the configuration schema is the same when the update will run as it is when you wrote the update function. So, when saving configuration, use the $has_trusted_data = TRUE parameter so that schema is ignored, and make sure that the configuration data you are saving matches the configuration schema at the time when you write the update function (later updates may change it again to match new schema changes).
• Never assume your field or entity type definitions are the same when the update will run as they are when you wrote the update function. Always retrieve the correct version via \Drupal::entityDefinitionUpdateManager()::getEntityType() or \Drupal::entityDefinitionUpdateManager()::getFieldStorageDefinition(). When adding a new definition always replicate it in the update function body as you would do with a schema definition.
• Never call \Drupal::entityDefinitionUpdateManager()::applyUpdates() in an update function, as it will apply updates for any module not only yours, which will lead to unpredictable results.
• Be careful about API functions and especially CRUD operations that you use in your update function. If they invoke hooks or use services, they may not behave as expected, and it may actually not be appropriate to use the normal API functions that invoke all the hooks, use the database schema, and/or use services in an update function -- you may need to switch to using a more direct method (database query, etc.).
• In particular, loading, saving, or performing any other CRUD operation on an entity is never safe to do (they always involve hooks and services).
• Never rebuild the router during an update function.

The following actions are examples of things that are safe to do during updates:

• Cache invalidation.
• Using \Drupal::configFactory()->getEditable() and \Drupal::config(), as long as you make sure that your update data matches the schema, and you use the $has_trusted_data argument in the save operation.
• Marking a container for rebuild.
• Using the API provided by \Drupal::entityDefinitionUpdateManager() to update the entity schema based on changes in entity type or field definitions provided by your module.

See https://www.drupal.org/node/2535316 for more on writing update functions.

Batch updates

If running your update all at once could possibly cause PHP to time out, use the $sandbox parameter to indicate that the Batch API should be used for your update. In this case, your update function acts as an implementation of callback_batch_operation(), and $sandbox acts as the batch context parameter. In your function, read the state information from the previous run from $sandbox (or initialize), run a chunk of updates, save the state in $sandbox, and set $sandbox['#finished'] to a value between 0 and 1 to indicate the percent completed, or 1 if it is finished (you need to do this explicitly in each pass).

See the Batch operations topic for more information on how to use the Batch API.

Parameters

array $sandbox: Stores information for batch updates. See above for more information.

Return value

string|null Optionally, update hooks may return a translated string that will be displayed to the user after the update has completed. If no message is returned, no message will be presented to the user.

Throws

\Drupal\Core\Utility\UpdateException|PDOException In case of error, update hooks should throw an instance of Drupal\Core\Utility\UpdateException with a meaningful message for the user. If a database query fails for whatever reason, it will throw a PDOException.

See also

Batch operations

Schema API

hook_update_last_removed()

update_get_update_list()

\Drupal\Core\Entity\EntityDefinitionUpdateManagerInterface

node_update_8001

system_update_8004

https://www.drupal.org/node/2535316

Related topics

Hooks

Define functions that alter the behavior of Drupal core.

Update API

Updating minor versions of modules

File

core/lib/Drupal/Core/Extension/module.api.php, line 619

Hooks related to module and update systems.

Code

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

  // Example function body for adding a field to a database table, which does
  // not require a batch operation:
  $spec = array(
    'type' => 'varchar',
    'description' => "New Col",
    'length' => 20,
    'not null' => FALSE,
  );
  $schema = Database::getConnection()->schema();
  $schema->addField('mytable1', 'newcol', $spec);

  // Example of what to do if there is an error during your update.
  if ($some_error_condition_met) {
    throw new UpdateException('Something went wrong; here is what you should do.');
  }

  // Example function body for a batch update. In this example, the values in
  // a database field are updated.
  if (!isset($sandbox['progress'])) {
    // This must be the first run. Initialize the sandbox.
    $sandbox['progress'] = 0;
    $sandbox['current_pk'] = 0;
    $sandbox['max'] = Database::getConnection()->query('SELECT COUNT(myprimarykey) FROM {mytable1}')->fetchField() - 1;
  }

  // Update in chunks of 20.
  $records = Database::getConnection()->select('mytable1', 'm')
    ->fields('m', array('myprimarykey', 'otherfield'))
    ->condition('myprimarykey', $sandbox['current_pk'], '>')
    ->range(0, 20)
    ->orderBy('myprimarykey', 'ASC')
    ->execute();
  foreach ($records as $record) {
    // Here, you would make an update something related to this record. In this
    // example, some text is added to the other field.
    Database::getConnection()->update('mytable1')
      ->fields(array('otherfield' => $record->otherfield . '-suffix'))
      ->condition('myprimarykey', $record->myprimarykey)
      ->execute();

    $sandbox['progress']++;
    $sandbox['current_pk'] = $record->myprimarykey;
  }

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

  // To display a message to the user when the update is completed, return it.
  // If you do not want to display a completion message, return nothing.
  return t('All foo bars were updated with the new suffix');
}