Problem/Motivation

In Drupal 8 there are two ways for a module to run configuration/schema/database updates. One is by creating a hook_update_N hook in your module's .install file. The other way is new to Drupal 8 and is to create a hook_post_update_NAME hook in your module's .post_update.php file.

Problems:

  • The documentation for these hooks do not mention the other at all.
  • The update API documentation does not mention even the existence of post_update hooks.
  • The only public discussion I could find about this is this DrupalCon Vienna talk from 2017, which mentions a "do's" and "don't"s list for what to put in update hooks, but no clear rules around it.

Proposed resolution

First, we need to establish hard and fast rules about these hooks. I don't know what they are. I generally just understand that it's not safe to put certain changes in hook_update_n(). But if it were as simple as that, then why not just use post_update for everything?

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

bkosborne created an issue. See original summary.

larowlan’s picture

Yes to this. I don't know half the time either and keep hassling jibran for confirmation

jibran’s picture

For me, there are three things to remember:

  1. post-update hooks run right after update_N hooks.
  2. update_N hooks are used when config or DB schema needs CRUD
  3. post-update hooks are used to update config entities, can be used for CRUD content entities but not recommended as site config might need and update see #2901418: Add hook_post_config_import_NAME after config import.

https://www.drupal.org/node/3034742 is a very good resource to understand the recommended way to install/update/uninstall entity types/fields in the update hooks.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Elijah Lynn’s picture

Slides showing differences from hook_update_n() and hook_post_update() from https://www.drupalgovcon.org/2020/program/sessions/using-post-update-scr... (recorded).

slide showing differences between hook_update_n and hook_post_update

instructions on how to use hook_post_update_NAME()

Pooja Ganjage’s picture

Hi,

From this below link, it shows difference between hook_update_N and hook_post_update functions.

https://events.drupal.org/vienna2017/sessions/update-hook-vs-post-update...

I hope it might help you out.

Thanks.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

bkosborne’s picture

Great write up by Matt Glaman and some more information in the comments on it: https://mglaman.dev/blog/hookupdaten-or-hookpostupdatename

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

adriancid’s picture

I think there is a clear explanation on this change record: hook_post_update_NAME() introduced to change content after hook_update_N() runs