8.3.x module.api.php hook_update_N(&$sandbox)
8.0.x module.api.php hook_update_N(&$sandbox)
8.1.x module.api.php hook_update_N(&$sandbox)
8.2.x module.api.php hook_update_N(&$sandbox)
8.4.x module.api.php hook_update_N(&$sandbox)
4.7.x install.php hook_update_N()
5.x install.php hook_update_N()
6.x install.php hook_update_N(&$sandbox)
7.x system.api.php 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.


  • 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.


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.


\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







Related topics

130 functions implement hook_update_N()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

aggregator_update_8001 in core/modules/aggregator/aggregator.install
The simple presence of this update function clears cached field definitions.
aggregator_update_8200 in core/modules/aggregator/aggregator.install
Make the 'Source feed' field for aggregator items required.
block_content_update_8001 in core/modules/block_content/block_content.install
Add 'revision_translation_affected' field to 'block_content' entities.
block_content_update_8002 in core/modules/block_content/block_content.install
Generalizes the d6_block_content_type and d6_block_content_body_field migrations.
block_content_update_8003 in core/modules/block_content/block_content.install
Add 'revision_created' and 'revision_user' fields to 'block_content' entities.

... See full list


core/lib/Drupal/Core/Extension/module.api.php, line 619
Hooks related to module and update systems.


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')
  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.
      ->fields(array('otherfield' => $record->otherfield . '-suffix'))
      ->condition('myprimarykey', $record->myprimarykey)

    $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');


DamienMcKenna’s picture

It really seems that with D8 it's really only safe to use hook_post_update_NAME() for most updates.

ericjenkins’s picture

Hi @DamienMcKenna, could you elaborate (or link to more information) as to why hook_post_update_NAME() is a better way to run updates than hook_update_N()?

bryanbraun’s picture

There are some more details about the downsides of hook_update_N in the change record: https://www.drupal.org/node/2563673

jasonyarrington’s picture

If you run drush updatedb you can see this in action. The hook_post_update_NAME() functions run after all the modules finish their hook_update_N() functions.

So, hook_post_update_NAME() is a safer (or more appropriate) place to make content updates. Also, hook_update_N() is supposed to be reserved for point version changes.

Performing rest_update_8203 [ok]
Performing block_content_update_8300 [ok]
Performing serialization_update_8302 [ok]
Performing update_update_8001 [ok]
Performing system_update_8301 [ok]
Performing views_update_8201 [ok]
Post updating block [ok]
Post updating block [ok]
Post updating contact

alex.designworks’s picture

In D8, update number is stored in `key_value` table under `system.schema` collection with a `name` of your module and `value` of the last ran update

RaisinBranCrunch’s picture

It says this in the documentation above, but it's not really clear. If you want to put a message for what the update is going to do before it is run, you'll need to add an annotation above the function:


* Update some table because of some reason.
function some_module_update_8101() {