Introduction to update API for Drupal 8

Last updated on
9 January 2017

What you need to update

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. In Drupal 8, there are several ways your data model can change, described in the following sections.

Content entity and field changes

TODO: Needs rewrite since automatic updates were removed.

Configuration schema changes

Changes to your configuration schema include:

  • Removing or renaming a configuration key.
  • Adding a configuration key. Even if the additions are backwards-compatible in terms of stored data, they will introduce unexpected differences in exporting configuration the next time the configuration is saved.
  • Changing the expected data type, allowable values, or array structure of a configuration key.
  • Changing the expected default value of a configuration key.
  • Changes to configuration dependencies (e.g. changes to a plugin's dependencies or an implementation of ConfigEntityInterface::calculateDependencies()).
  • Etc.

For example, changing the way a particular Views plugin defines its configuration would require an update to all saved views configuration items that use that plugin.

Database schema changes

If your module defines its own hook_schema() for database tables, the following types of changes are possible:

  • Adding, changing, or removing a database table or field.
  • Moving stored data to different fields or tables.
  • Changing the format of stored data (for example, changing the stored format of user-entered paths, requiring a different password hashing algorithm, or storing a UUID as an external key instead of a serial ID).

Writing update code

Once you have identified that your module is making a data model change you will need to use hook_update_N() to provide code that updates data so that it fits with your new data module. How to do this depends on the type of data model change (see previous section for list) and the specifics are covered in other pages (except the common piece in the skeleton of hook_update_N() section below):

Content entities and fields
This is covered on the child page about entity and field updates.
Configuration
This is covered on the child page about configuration updates.
Database schema
This is covered on the child page about database updates.

Skeleton of hook_update_N()

All update code will need to go into a "hook_update_N()" function. Assuming your module's short/machine name is "mymodule", this goes into your mymodule.install file, and looks something like this:

/**
 * Write a line or two here about what the updates are for.
 * This is shown to users on the update.php page.
 */
function mymodule_update_8001(&$sandbox) {
}

Each time you update your data model, you need to define a new function separate from previous ones. Each individual update function needs to be given a unique function name, so there is a numeric suffix (8001 in this example). Compose your numeric suffix as follows:

  • 1 digit for Drupal core compatibility (8)
  • 1 digit for your module's major release version. For instance, if you're developing for Drupal Core and its version 8.0.x, use 0, and if its version 8.1.x, use 1, etc. If you're in a contrib or custom module, and its version 8.x-1.x, use 1, etc.
  • 2 digits for sequential counting, starting with 01. (Note: starting at 01 is required. Starting at 00 can cause system schema corruption.)

So in the example here, this is the first update for a Drupal 8 core module in the 8.0.x series.

Testing updates

Updates should be tested. Ideally, they would be tested manually, and there would also be an automated test.

Testing updates manually

To test your update code manually, or to see whether you need to write your own update code for a data model change:

  • Start with a site that is running your old code, and add some data related to this code (content, configuration, etc.).
  • Apply the code change or patch to the site.
  • Visit the update.php page and run any available updates.
  • Manually try using the data in the relevant parts of the UI (view the content, view pages that are generated from the configuration, etc.). See if it all works without error messages.

Writing automated tests for updates

This is covered in the child page about automated tests.