Best practices for upgrading Drupal (6->7) and CiviCRM (3->4) at the same time

2013-04-11 12:16
Written by

The attached chart came out of a discussion between Kasia Wakarecy, Lola Slade and myself (Lynna Landstreet), at Freeform Solutions, about some issues we'd encountered when trying to to do major version upgrades of CiviCRM and Drupal on a client's site at the same time. Since we're likely to have a number of other combined upgrades like that to do in the future, we wanted to iron out the best process for doing them as smoothly as possible.

And we thought it might be useful to share what we’ve got thus far with others in the CiviCRM community, partly because it might help other people, and partly to find out others’ experiences: do you agree with what we’ve outlined here? Disagree? Have anything you’d want to add/change? We’re thinking of contributing this to the wiki documentation, but wanted to post it here for discussion first.

The pink boxes on the chart represent the actual steps involved, with the green ones being the state of the site(s) you’re working on between the various steps. Blue diamonds are decision points.

A few comments on the steps involved:

  1. The first and most important thing we found was that you really, really need to upgrade CiviCRM first and Drupal second. 

    The reason for this is that in order for CiviCRM's upgrade script to run successfully, the module has to be enabled - but if you've just upgraded from Drupal 6 to 7, all Drupal 6 modules are disabled automatically, so the CiviCRM upgrade script won't run. And CiviCRM 3.x is not compatible with Drupal 7, so there's no way to have CiviCRM enabled under Drupal 7 until after you've upgraded it to 4.x. 

    So the first thing you need to do is upgrade CiviCRM to the DRUPAL 6 VERSION of CiviCRM 4.x (where 4.x is whatever version is current at the time of the upgrade - at the time of writing this, it's 4.2.8), with the site in maintenance mode, of course, if you’re doing this on the live site. This part should be fairly straightforward, unless your CiviCRM installation is particularly complex or customized. Also, if you’re running CiviCRM 3.2 or earlier, you’ll probably want to upgrade in stages, rather than going all the way 4.x in one step, or else you may have trouble with the upgrade script timing out.
  2. The next thing you need to do is clone the site to a development environment (in other words, make a copy of it to use a test site for the Drupal upgrade). 

    Why not do this before upgrading CiviCRM? Because the Drupal upgrade will probably be more involved and take longer - and while you're doing that, chances are there's going to be activity going on in CiviCRM, which you don't want to lose by copying the upgraded database back to the live site once it's all done. And that activity will probably result in changes or additions to a variety of different database tables, making it much harder to merge the changes into the new database.


So paradoxically, it's safer to upgrade CiviCRM on the live site, and only Drupal on the dev site, unless you're willing to keep the site in maintenance mode for the entire process, which is more downtime than most site owners want.

  3. Next, do the Drupal 6 to 7 upgrade on the dev site, and deal with any issues or problems that arise during that process (because there will nearly always be some). The note in the chart about keeping track of any issues and how you resolved them (or what you ought to have done differently) is especially important if it's a highly active site, for reasons that will become clear shortly.
  4. Next you have a decision to make: how much integration is there between CiviCRM and Drupal? If it's just a fairly standard CiviCRM installation, you can probably just keep CiviCRM disabled for now (since the Drupal 6 => 7 upgrade will have automatically disabled it), until you get to the last step of the process.

    But if you're got integration between CiviCRM and Views or OG, or anything of similar complexity, you're more likely to encounter issues and will need to do more testing. So if that's the case, you'll want to replace the D6 version of CiviCRM on your dev site with the D7 version of the same version of CiviCRM — i.e. CiviCRM 4.2.8 for Drupal 6 to CiviCRM 4.2.8 for Drupal 7 and run update.php, and then check for problems with your views, groups, etc. And of course, make note of what you encountered and how you fixed it.

    Why does it have to be the same version of CiviCRM? Because trying to go to a different version would mean running the CiviCRM upgrade script, which won't run when CiviCRM has been disabled by the Drupal upgrade process, remember? Also, the version specified in the database needs to match, or you may encounter problems.

  5. Now you've got another decision to make: in however long it's taken you to do all this, how much activity has there been in Drupal, on the live site? (As opposed to within CiviCRM, which is pretty much a given.) If you're not sure, check the databases for both sites, particularly the node_revisions, comments and users tables, which tend to be the most frequently updated. Then put both the live and dev sites into maintenance mode and do whichever of the following seems most suitable: 

    a. If there haven't been any changes, go ahead and copy the files and database from the dev site back to the live site. (NOT the CiviCRM database, mind you, just the Drupal database. If they use the same database, copy just the Drupal tables, not the CiviCRM tables.)

    b. If there have been a few changes, but not many, you can probably just manually make the changes to the dev site (adding the new nodes, users, etc.) and then copy things over as above. 

    c. If there have been a lot of changes, as may happen on a highly active site, then it's probably going to be easier to just redo the Drupal upgrade directly on the live site. This may seem like doing it on the dev site first was a waste, but it’s better to get all the problems out of the way somewhere other than on a busy live site, so that when you do come to upgrade the live site, everything will go more smoothly. (You did remember to note down everything you did and how you resolved any problems that came up, right?)

  6. Regardless of which path you took at each of the above question points, you should now have a fully functioning, live Drupal 7 site, with the (disabled) Drupal 6 version of the current version of CiviCRM. 

So the last thing you need to do is upload the Drupal 7 version of the same version CiviCRM, overwriting the Drupal 6 one, and run update.php.


And voila! A fully upgraded, Drupal 7/CiviCRM 4 site!
Attachment Size
Flow chart showing upgrade steps105.8 KB 105.8 KB


Thanks for sharing your hard-won learnings with the community - I'm sure this will save lots of folks time and heartache. This is a great example of the open source community spirit!

Annoyingly it is not possible to render that page in a printable form (ie without the navigation stuff on the left side, and if you try to porint the page as it stands, you lose the rightmost few characters on each line.

So until that is fixed here is a printable version of these guidelines.  (Too bad I cannot create new attachments on this web site so you're going to have to download it from my web site.)


Thanks for sharing these detailed instructions! Has any additional useful information for the process been unearthed since they were written? Was it added to a Wiki?