Update API

The Update API is Drupal's set of hooks, such as hook_update_N() and hook_post_update_NAME(), that bring existing sites' stored data up to date.

Learn DrupalDrupal glossary
Edited by Founder and CEO, DXPR Last updated

The Update API is the part of Drupal that lets a module change the data it has already stored when its code changes. A module adds an update function; Drupal notices that the function has not run yet, and runs it once, in order, when you open update.php or run drush updatedb. Sites moving from Drupal 6 or 7 use the Migrate API instead.

How it works in Drupal 11

A module needs update code when a change makes stored data on existing sites incompatible with the new code. Core names three kinds: configuration changes such as a renamed key, database schema changes, and changes to content entity or field definitions.

  • hook_update_N() goes in my_module.install and is named my_module_update_NNNN(). The number must be higher than whatever hook_update_last_removed() returns. By convention it combines the core version, the module's major version and a two-digit counter, and the lowest number Drupal recognizes is 8001.
  • hook_post_update_NAME() goes in my_module.post_update.php. It runs after all hook_update_N() functions, when Drupal is fully bootstrapped, and it is skipped when the module is first installed.
  • hook_update_dependencies() orders updates across modules, hook_update_last_removed() declares the highest number deleted from the file, and hook_removed_post_updates() does the same for post-update names.

Long jobs take a $sandbox argument. The function does one chunk of work and sets $sandbox['#finished'] to a value between 0 and 1; Drupal calls it again until it reaches 1. To report a failure, throw Drupal\Core\Utility\UpdateException.

Example

A module adds a subtitle column to its own table. Core strips the line breaks from the docblock above the function and shows the result as the description on the pending updates list.

/**
         * Adds the subtitle column to the my_table table.
         */
        function my_module_update_11101() {
          $spec = [
            'type' => 'varchar',
            'description' => 'Subtitle.',
            'length' => 255,
            'not null' => FALSE,
          ];
          \Drupal::database()->schema()->addField('my_table', 'subtitle', $spec);
        }

The number 11101 reads as core 11, module major version 1, update 01.

Common mistakes

  • Calling hook_schema() inside an update. The schema may have changed again by the time the update runs. Copy the field definition into the function instead.
  • Saving entities in hook_update_N(). Core says loading, saving or any other entity operation is never safe there, because it involves hooks and services. Use hook_post_update_NAME() for that.
  • Saving configuration without trusted data. Core says to pass $has_trusted_data = TRUE, and to match the schema as it was when you wrote the update.
  • Rebuilding the router during an update. Core forbids it. Invalidating caches is safe.

For marketing and content teams

You will see the Update API only as a pending-updates screen or a Status report line. If the Status report shows Database updates as Out of date, a module has update functions waiting, and Drupal's own message says to run the update script immediately. Ask your developers to run them; editors should not have to.

Sources

Questions about Update API

No. The Update Status module in core checks drupal.org for new releases and lists them in the Available updates report. The Update API is the code pattern a module uses to change its stored data after you install a new release. The two share a word, nothing more.

For hook_update_N(), it stores the last number each module ran in the system.schema key-value store. Core's own text says to never renumber update functions, because that number is what the database remembers. Post-update functions are tracked by name instead.

Not in Drupal 11.4. The core documentation says only procedural implementations are supported for hook_update_N(), hook_post_update_NAME(), hook_update_dependencies() and hook_update_last_removed(). They are plain functions in the module's .install or .post_update.php file.

Related terms

All Drupal terms from A to Z