I looked for instructions on how to update a Drupal module, but could not find any good ones. I did find some, but they were dangerously incomplete. Therefore I will now write down how I do it, hoping for hints at possible improvements.

  1. Download the new version of the module and unpack it, so you have the module folder ready on your local disk (or in a location outside your Drupal installation on the server). The folder usually bears the short name of the module and contains a file also bearing the short name of the module, followed by ".module". Most also contain a README.txt file, which you may want to read and check for special update instructions.
  2. Make sure your latest complete backup is not too old. A module change, if well done, poses only a small risk of database corruption, but it is better to be safe than sorry.
  3. Make sure you are logged in as admin (user #1). This is necessary for later steps. If you are logged on as another user, log off, then log on again as admin.
  4. Fire up your ftp program or whatever you use to work with files on the server and connect to the server. You want to minimize the downtime, so prepare yourself as well as possible before you take the site offline.
  5. Put the entire site into maintenance mode (Administer, Site configuration, Site maintenance). If you are a nice operator, you can add some text to the message, stating why the site is offline and when it will be back online, for example: "A module of this web site is being updated. Work should be finished on the full hour. Please check back then."

    The reason for entering maintenance mode is that you don't want web visitors to call up module code while that same module code is missing, incomplete, or being deleted or written. That would lead to ugly temporary errors or, in the very worst case, to database corruption. An alternative would be to disable the module temporarily, but you need maintenance mode for the later running of update.php anyway.

    Warning: Do not uninstall the module, because that would likely lead to the loss of all data the module may have kept in the database.

  6. Using your ftp or similar program, delete the module's entire folder on the server. It is usually in /site/all/modules/.
  7. Copy the new module into the place where the old one was.
  8. Make sure again that you are logged on as admin, then run update.php. To do that, you enter the URL of your Drupal web site in the web browser, followed by /update.php. Example: http://winhlp.com/update.php

    Go through the steps of the update procedure. The most important point here is to check the displayed log for any errors. If there are errors, you have to find out what went wrong, before you put the site back online.

  9. If there are no errors, end maintenance mode to put your site back online. The simplest way to do that with one mouse click is to go to the Site maintenance page again and click on the button [Reset to defaults]. That's it, your site has been successfully upgraded and is now back online.

If you find any fault in these instructions, please add a comment.

Comments

heather’s picture

Add: "mv the old version of the module to some backup place, to make it easier to revert if necessary."

This is a very good list.

We might want to integrate this into the Handbook.

hgmichna, where would you have expected to see this? Where do you think it should go?

We can amend and improve an existing handbook page (easier), or propose a new one (harder)

hgmichna’s picture

I don't know the handbook structure very well, so if anybody wants to move or copy this, please go ahead. I reserve no copyright. (:-)

As to reverting, that's a can of worms. If the user has already run update.php, which will practically always be the case, then it may not be possible for the user to find out whether the old version is still compatible with the modified database. In effect there's no going back, unless you also revert the database, i.e. restore an entire backup.

Embarquer’s picture

Inspired by Atul Gawande's, The Checklist Manifesto : how to get things right, I have tried to turn the above into more of a "pilot's checklist" for trying out.

Upgrade Drupal Module Checklist (based on http://drupal.org/node/672472)

  1. Get new module version: Download the new version of the module and unpack it, so you have the module folder ready on your local disk (or in a location outside your Drupal installation on the server). The folder usually bears the short name of the module and contains a file also bearing the short name of the module, followed by ".module". Most also contain a README.txt file, which you may want to read and check for special update instructions.
  2. Check most recent database backup: Make sure your latest complete backup is not too old. A module change, if well done, poses only a small risk of database corruption, but it is better to be safe than sorry.
  3. Log in as Administrator (User 1): Make sure you are logged in as admin (user #1). (User #1 is the very first user named during web site creation.) This is necessary for later steps. If you are logged on as another user, log off, then log on again as admin.
  4. Start your FTP program: Fire up your ftp program or whatever you use to work with files on the server and connect to the server. You want to minimize the downtime, so prepare yourself as well as possible before you take the site offline.
  5. Set site status to 'Off-line': Put the entire site into maintenance mode (Administer -> Site configuration -> Site maintenance). If you are a nice operator, you can add some text to the message, stating why the site is offline and when it will be back online, for example: "A module of this web site is being updated. Work should be finished on the full hour. Please check back then."

    The reason for entering maintenance mode is that you don't want web visitors to call up module code while that same module code is missing, incomplete, or being deleted or written. That would lead to ugly temporary errors or, in the very worst case, to database corruption. An alternative would be to disable the module temporarily, but you need maintenance mode for the later running of update.php anyway.

    Warning: Do not uninstall the module, because that would likely lead to the loss of all data the module may have kept in the database.

  6. Backup old module's folder: Copy the old module's folder to some backup place, to make it easier to revert if necessary.
  7. Delete old module's folder: Using your ftp or similar program, delete the module's entire folder on the server. It is usually in ../site/all/modules/.
  8. Copy new module's folder: Copy the new module into the place where the old one was.
  9. Run ../update.php: Make sure again that you are logged on as admin, then run update.php. To do that, you enter the URL of your Drupal web site in the web browser, followed by /update.php. Example: http://winhlp.com/update.php

    Go through the steps of the update procedure. The most important point here is to check the displayed log for any errors. If there are errors, you have to find out what went wrong, before you put the site back online.

  10. If no errors, set site status to 'Online': If there are no errors, end maintenance mode to put your site back online. The simplest way to do that with one mouse click is to go to the Site maintenance page again and click on the button [Reset to defaults]. That's it, your site has been successfully upgraded and is now back online.

If you find any fault in these instructions, please add a comment.

hgmichna’s picture

Looks very good. I think your version should be used, if someone wants to insert it into the manual.

ShadowCaster’s picture

In step 7, I believe that "It is usually in ../site/all/modules/." should be "It is usually in ../sites/all/modules/." (At least that is the case for my website.)

BTW, I'm glad to see that disabling and reenabling the modules is not required. I've seen that in other instructions and it was a big pain.

hgmichna’s picture

Correct. The universal add-on modules are in: .../sites/all/modules/

As to the disabling and reenabling of modules, my reasoning is, if nobody can get into the web site and use it, the modules are essentially sleeping and not used. So why disabling them?

Poormanscron or similar timed modules may be an exception, but even there it is highly unlikely that they stumble, because the deletion of a module is a pretty quick operation. Still one might want to disable Poormanscron before deleting it and copying a new version in its place.

ShadowCaster’s picture

So why disabling them?

My bad, I was getting the instructions for updating a module confused with updating the Drupal core, which does call for disabling all custom and contributed modules first.

ShadowCaster’s picture

Oh, and one other thing. Shouldn't the backup be taken while the site is in the offline state, just to minimize the chance that someone is in the middle of changing it?

Also, it would be helpful if there was a description some place of the process of taking the backup. Usually there's a way to do it from some sort of control panel, but I have found the following command line works well too. (Of course, I've never been called upon to perform a restore, so I don't have a restore version version of this.)

DATE=`date +%Y%m%d`
mysqldump -h database.url -u database.admin.id -pdatabase.admin.password database.name >database.name.$DATE.backup

hgmichna’s picture

As I mentioned, it is difficult to imagine how a module update could possibly corrupt the database, provided that the module does not get activated during the update.

That's why I think that any recent backup is good enough. I don't really see the need for a fresh backup before a module update.

Losing, say, three days of recent database updates once every 100 years is a risk I would take. But this depends on how important the web site is.

molave’s picture

Was just wondering what might happen if some scheduled (but forgotten) task were to run in the middle of the update process, like maybe a regular database backup or something else. Even with DSL, after all, uploading some of the larger module folders could take a while.

Would it be prudent to disable automated tasks things for a while.. or would that be overkill?

Just wondering.

mot’s picture

It's okay to call update.php everytime - it just does not hurt. But in case you wonder if it does not show any updates in the drop-down listboxes, it means there is nothing to update. This is for the database version or something database related. So it's not always a need in the end to call that script. In case you do not know if or not: call it.

betoth’s picture

If you want to make your checks more comprehensive, you should add a line after 8 to check the permissions of files in the module. Should be set to user:www-data for apache, etc... with permissions rw-r----.

ssace’s picture

One note I might add is be aware of any .dev modules you may be running. When switching from a .dev to a production release or vice versa, you may be required to uninstall the existing and fresh install the new one. As a practice, I pay attention to the version I am upgrading to as well as the readme documentation. Generally, if you stay within the distribution branch you are ok to do all the above without any problems.

DrupalNovice’s picture

Good point!

ben soo’s picture

i wish there was a way of updating modules and themes that's as simple as module + theme installation with D7, where i could just use the browser to select the proper module update with a few clicks, and it'd be uploaded, unpacked and installed for me. It's so much easier than doing it by hand espesh on sites with a large number of modules.

With the pace of development in Drupal, over the years updating dev modules and themes have been a pretty constant and dreary task, first thing i do every time i put on my Drupal admin hat.

ben soo’s picture

ok, never mind: i see that there is a module update process built into D7.

Just didn't see it. Guess i better do some GC on my brain, or reboot it.

DrupalNovice’s picture

Good point!

andiart’s picture

What for are the numbers like 6000, 6001... in the selectboxes in update process per module?
And can I always choose the latest number?

Because sometimes the latest number is already chosen - sometimes a new modules select box has already the latest version and sometimes it has some number in the middle preselected.

nehajn’s picture

Hi
when we are updating modules then which step we have to follow.
after replacing the disabled module to new one .
we will go for run update.php
OR
I have to enable new module first and then run update.php.
Any suggestions?
I am little confused with in that

nehajn’s picture

Steps to update contributed module for the minor version -

Drupal 6 :

1. Take DB and code complete backup

2. Download the latest release of module for used drupal 6.x version .

3. Delete the old module folder from your site/all/modules directory .
Upload new module at here.

4. Then run update.php .

5. During update ,automatically update will detected and executed if there is also db update available.

No need to disable module because to run update.php ,module should be in enabled state .

Thanks

codeinvaders’s picture

I need a specific version of a module never updated, as it has changed the code to behave differently. Where should I install the module? In what folder?
Greetings and thanks!!!

nehajn’s picture

download the module form drupal.org then extract into you website at given path-
yoursite/sites/all/modules
If modules directory is not present then create and paste folder here
then go to yoursite/admin/build/modules/list and checked the module and save.
Now you can utilize the module functionality.
Update is not an issue ,its a method to extend the features of module so not to worry on that.

Doi2oioi@rogers.com’s picture

Thank you for your instructions on updating modules.
I am new to this and have just been given the administrator role for a web site. I find that there are numerous modules updates to do.
So could I update each one at the same update/maintenance time or must one do each module separately as explained by your instructions?
Does this make any sense?
Thanks, Jean-Paul

cigotete’s picture

related with this process (updating modules), I am curious about if is necessary clear the cache of the site when site goes off line. ¿this task is necessary? I make the question because I see that web pages of the drupal site (caching mode: normal -> enabled) is served when the site is "off line", the "off line" message is not displayed, and indeed the site is off line. so, clear (or not clear) the chache could be a problem?

Jay.Chen’s picture

To use the quick update module to install multiple new projects or all the missing dependency projects.

sri@re’s picture

how to update custom module using update module. Is there any repository available for drupal 7 to update all files (including css , scripts and modules).?

please clarify.