Update API

Same name in other branches
  1. 7.x modules/system/system.api.php \update_api
  2. 9 core/lib/Drupal/Core/Extension/module.api.php \update_api
  3. 10 core/lib/Drupal/Core/Extension/module.api.php \update_api
  4. 11.x core/lib/Drupal/Core/Extension/module.api.php \update_api

Updating minor versions of modules

When you update code in a module, you may need to update stored data so that the stored data is compatible with the new code. If this update is between two minor versions of your module within the same major version of Drupal, you can use the Update API to update the data. This API is described in brief here; for more details, see https://www.drupal.org/node/2535316. If you are updating your module for a major version of Drupal (for instance, Drupal 7 to Drupal 8), updates will not run and you will need to use the Migrate API instead.

When to write update code

You need to provide code that performs an update to stored data whenever your module makes a change to its data model. A data model change is any change that makes stored data on an existing site incompatible with that site's updated codebase. Examples:

  • Configuration changes: adding/removing/renaming a config key, changing the expected data type or value structure, changing dependencies, schema changes, etc.
  • Database schema changes: adding, changing, or removing a database table or field; moving stored data to different fields or tables; changing the format of stored data.
  • Content entity or field changes: adding, changing, or removing a field definition, entity definition, or any of their properties.

How to write update code

Update code for a module is put into an implementation of hook_update_N(), which goes into file mymodule.install (if your module's machine name is mymodule). See the documentation of hook_update_N() and https://www.drupal.org/node/2535316 for details and examples.

Testing update code

Update code should be tested both manually and by writing an automated test. Automated tests for update code extend \Drupal\system\Tests\Update\UpdatePathTestBase -- see that class for details, and find classes that extend it for examples.

See also

Migrate API

File

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

Functions

Title File name Summary
hook_post_update_NAME core/lib/Drupal/Core/Extension/module.api.php Executes an update which is intended to update data, like entities.
hook_removed_post_updates core/lib/Drupal/Core/Extension/module.api.php Return an array of removed hook_post_update_NAME() function names.
hook_updater_info core/lib/Drupal/Core/Extension/module.api.php Provide information on Updaters (classes that can update Drupal).
hook_updater_info_alter core/lib/Drupal/Core/Extension/module.api.php Alter the Updater information array.
hook_update_dependencies core/lib/Drupal/Core/Extension/module.api.php Return an array of information about module update dependencies.
hook_update_last_removed core/lib/Drupal/Core/Extension/module.api.php Return a number which is no longer available as hook_update_N().
hook_update_N core/lib/Drupal/Core/Extension/module.api.php Perform a single update between minor versions.

Classes

Title Deprecated File name Summary
UpdatePathTestBase Deprecated core/modules/system/src/Tests/Update/UpdatePathTestBase.php Provides a base class for writing an update test.
UpdatePathTestBase core/tests/Drupal/FunctionalTests/Update/UpdatePathTestBase.php Provides a base class for writing an update test.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.