function hook_update_N

Same name in other branches

7.x modules/system/system.api.php \hook_update_N()
8.9.x core/lib/Drupal/Core/Extension/module.api.php \hook_update_N()
10 core/lib/Drupal/Core/Extension/module.api.php \hook_update_N()
11.x core/lib/Drupal/Core/Extension/module.api.php \hook_update_N()

Perform a single update between minor versions.

Modules should use hook hook_update_N() to update between minor or major versions of the module. Sites upgrading from Drupal 6 or 7 to any higher version should 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 number (N) must be higher than hook_update_last_removed().

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. If your module is compatible with multiple major versions (e.g., it has a core_version_requirement of '^8.8 || ^9'), use the lowest major core branch it is compatible with (8 in this example).
1 or 2 digits for your module's major release version. Examples:
- For 8.x-1.* or 1.y.x (semantic versioning), use 1 or 01.
- For 8.x-2.* or 2.y.x, use 2 or 02.
- For 8.x-10.* or 10.y.x, use 10.
- For core 8.0.x, use 0 or 00.
- For core 8.1.x, use 1 or 01.
- For core 8.10.x, use 10.
This convention is optional but suggested for clarity. Note: While four- digit update hooks are standard, if you follow the above convention, you may run into the need to start using five digits if you get to a major (or, for core, a minor) version 10. This will work fine; what matters is that you must ALWAYS increase the number when a new update hook is added. For example, if you add hook_update_81001(), you cannot later add hook_update_9101(). Instead, you would need to use hook_update_90101().
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 is 8001.

@todo Remove reference to CORE_MINIMUM_SCHEMA_VERSION (e.g., x001) once https://www.drupal.org/project/drupal/issues/3106712 is resolved.

Examples:

node_update_8001(): The first update for the Drupal 8.0.x version of the Drupal Core node module.
node_update_81001(): The first update for the Drupal 8.10.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.
mymodule_update_80201(): Alternate five-digit format for the first update for the 8.x-2.x versions. Subsequent update hooks must always be five digits and higher than 80201.
mymodule_update_8201(): The first update for the custom or contributed module's 2.0.x versions, which are compatible with Drupal 8 and 9.
mymodule_update_91001(): The first update for the custom or contributed module's 10.0.x versions, which are compatible with Drupal 9.

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

Parameters

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.

Throws

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

File

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

Code

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 = [
        'type' => 'varchar',
        'description' => "New Col",
        'length' => 20,
        'not null' => FALSE,
    ];
    $schema = Database::getConnection()->schema();
    $schema->addField('my_table', '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([my_primary_key]) FROM {my_table}')
            ->fetchField();
    }
    // Update in chunks of 20.
    $records = Database::getConnection()->select('my_table', 'm')
        ->fields('m', [
        'my_primary_key',
        'other_field',
    ])
        ->condition('my_primary_key', $sandbox['current_pk'], '>')
        ->range(0, 20)
        ->orderBy('my_primary_key', 'ASC')
        ->execute();
    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.
        Database::getConnection()->update('my_table')
            ->fields([
            'other_field' => $record->other_field . '-suffix',
        ])
            ->condition('my_primary_key', $record->my_primary_key)
            ->execute();
        $sandbox['progress']++;
        $sandbox['current_pk'] = $record->my_primary_key;
    }
    $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');
}

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

function hook_update_N

Naming and documenting your function

Notes about the function body

Batch updates

Parameters

Return value

Throws

See also

Related topics

File

Code

Search drupal 9

API Navigation

Breadcrumb

function hook_update_N

Naming and documenting your function

Notes about the function body

Batch updates

Parameters

Return value

Throws

See also

Related topics

File

Code

Search drupal 9

API Navigation