How does Drupal know when to run an update script?

Question

How does Drupal 8 know what module needs updating and to what version he needs to update?

I have build a module and I'm trying to update it (adding a table). I implemented a update hook numbered 8001, which is the first update, but when I go to update.php Drupal does not see any update for my module.

I expect there must be a place in my module where I can define the current version of my module and another place in the database where Drupal stores the latest installed update of my module. (I need this for debugging the update script later on.)

Answer 1

To store/get the version information for a module use the global functions:

drupal_set_installed_schema_version()
drupal_get_installed_schema_version()

For example set a new version for mymodule with drush:

drush ev "drupal_set_installed_schema_version('mymodule', '8123')"

Print the version with drush, in this example for the module comment:

drush ev "var_dump(drupal_get_installed_schema_version('comment'))"

The functions are defined in schema.inc. Here you can see how to access the key_value table through the keyvalue api, if you want to use your own code:

/**
 * Updates the installed version information for a module.
 *
 * @param string $module
 *   A module name.
 * @param string $version
 *   The new schema version.
 */
function drupal_set_installed_schema_version($module, $version) {
  \Drupal::keyValue('system.schema')->set($module, $version);
  // Reset the static cache of module schema versions.
  drupal_get_installed_schema_version(NULL, TRUE);
}

Answer 2

I expect there must be a place in my module where I can define the current version of my module

When you install a module, Drupal checks the update hooks, and stores the higher number your update hooks have (e.g. 8004). That value is then stored in \Drupal::keyValue('system.schema'). Drupal then uses that value when it checks again the higher value associated with the update hooks of your module; if that number is higher than the number it stored, it knows there is an update for your module.

You can use \Drupal::keyValue('system.schema')->getAll() to get an array of latest versions for all the modules, stored using the module short name as index. You can use \Drupal::keyValue('system.schema')->setMultiple() to save the array once you changed it.

Answer 3

SELECT * FROM key_value WHERE collection = "system.schema"

The schema value stored in BLOB format.