Many functions in Drupal are not allowed to be called from inside hook_update_N(), often because they will break things when the module is updated while it is disabled.

For some fun background reading:
#734710: API functions that invoke hooks don't work as expected when a disabled module is being uninstalled
#773828: Upgrade of disabled modules fails

For Drupal 7, the suggested solution in the second issue was to document this better, so that is what this issue is about. It's pretty tricky, though. Some of your own module's API functions can be used in hook_update_N() if you specifically load your .module file, but that won't work for all of them. And a number of standard Drupal API functions won't work correctly either. See for example:
#717902: Updated DB schema not available in module update functions
#737816: user_role_grant_permissions() throws PDOException when used with non-existent permissions (e.g. a permission for a disabled/uninstalled module)

Files: 
CommentFileSizeAuthor
#7 794192-7-document-install.patch861 byteskim.pepper
PASSED: [[SimpleTest]]: [MySQL] 40,358 pass(es).
[ View ]
#5 794192-document-install.patch861 byteskim.pepper
PASSED: [[SimpleTest]]: [MySQL] 40,737 pass(es).
[ View ]

Comments

Category:task» bug

Marking as a bug in documentation.

This is a complex issue, but it should be fixed...

Version:7.x-dev» 8.x-dev
Issue tags:+Novice, +needs backport to D7

I am reviving this issue.

We actually have a separate issue right now that is taking care of documenting that you can't use the schema or hooks:
#1134088: Properly document update-api functions

So I think all we need to document here is that if you use a function from your .module file or an include file, you need to load that file. That should actually be a good Novice issue, and I think we should do it in 8.x (at least for now, because I don't really think that #773828: Upgrade of disabled modules fails is likely to be fixed any time soon).

Status:Active» Needs review
StatusFileSize
new861 bytes
PASSED: [[SimpleTest]]: [MySQL] 40,737 pass(es).
[ View ]

Added documentation for #4

Status:Needs review» Needs work

Looks good!

A bit of a comma problem though... I think we either need to remove the comma in the first line here, or add another one at the end:

+ * In order to call a function from your mymodule.module, or an include file
+ * you need to explicitly load that file first.

StatusFileSize
new861 bytes
PASSED: [[SimpleTest]]: [MySQL] 40,358 pass(es).
[ View ]

Here's another attempt with correct comma implementation. I should have paid more attention in grammar classes.

Kim

Status:Needs work» Reviewed & tested by the community

That looks better, thanks! When attaching a patch, you need to set to "needs review" to launch the test bot and alert human reviewers too (I'm going directly to RTBC which will also launch the test bot).

Status:Reviewed & tested by the community» Fixed

Thanks! Committed to 8.x and 7.x.

Status:Fixed» Closed (fixed)
Issue tags:-Novice, -needs backport to D7

Automatically closed -- issue fixed for 2 weeks with no activity.