Before beginning this upgrade, verify that your server meets the requirements for CiviCRM 3.4.

  • CiviCRM 2.2.x+ : You must be running CiviCRM 2.2.x to use this upgrade. Running a version prior to 2.2? First upgrade to 2.2 using these instructions
  • Drupal 6.x : CiviCRM 3.4 has been built to run under Drupal 6 and is not compatible with Drupal 5 nor 7 sites.
  • PHP 5.2.x  or 5.3.x :  CiviCRM will NOT run on PHP4 servers. (more info...).
  • MySQL 5.0.x or higher with InnoDB support : CiviCRM is compatible the current generally available MySQL release. Note that MySQL 5.1 is recommended for new installations and for sites during upgrades as CiviCRM is beginning to use Triggers more (eg to support multi-lingual installations), which require SUPER privileges in MySQL 5.0.
  • PCRE with Unicode properties support (more info).

We strongly recommend that you create a copy of your existing site (directories and database) - and upgrade that copy first in order to make sure you can complete the upgrade successfully. In any case, you should create a full backup of the installed civicrm directory tree and civicrm database before beginning the upgrade process.
If you are upgrading a COPY of your production site - make sure the site you are about to upgrade is a fully functioning installation before you begin the upgrade process. (more info...)

Step-by-step Upgrade Procedures

1. Download the most recent CiviCRM Package

2. Take the Site Offline (for production site upgrades)

When upgrading a production site, it is recommended that you take your site offline during the upgrade process.
Administer » Site Configuration » Site Maintenance

3. Ensure that CiviCRM is not your Drupal homepage

Due to changes in Dashboard files from 3.0 to 3.1, you need to ensure that your Drupal homepage is not the CiviCRM homepage. If your site does use CiviCRM as its front page, change it by clicking on:
Administer » Site Configuration » Site Information
Then ensure that the "Default front page" value is not civicrm (change it to node if necessary). If you made a change, click Save configuration

NB: there are a variety of modules that may affect the Drupal homepage. Consult the appropriate module's documentation if you are using them to set the homepage to civicrm for the administrative action required to change to a different non-CiviCRM homepage for the upgrade process.

4. Disable all CiviCRM integration / extension modules (NOT CiviCRM itself)

If you have modules installed in your Drupal site that integrate with or extend CiviCRM functionality, you should disable them prior to running the upgrade script. This will prevent modules that are not compatible with the new version from triggering errors in the upgrade process.

Administer » Site Building » Modules

Note which modules in the CiviCRM section of the modules listing are currently enabled (taking a screenshot is one easy way to do this). Now un-check the Enabled box for ALL modules in the CiviCRM section of the modules listing EXCEPT for CiviCRM itself. Click Save.

Do NOT disable CiviCRM itself. Only disable other modules in the CiviCRM section of the modules page. The upgrade will NOT run if CiviCRM is disabled.

5. Backup your CiviCRM database

Refer to the MySQL reference manual or the phpMyAdmin documentation if you need information on backing up your database.

6. Backup and then delete all previous version code files

CiviCRM will not run properly if files from previous version are present after the upgrade. Make sure you have a good backup of your complete previous version installation and then delete /sites/all/modules/civicrm.

Be sure that your backup copy of the previous version codebase is NOT located below the <drupal home>/modules or <drupal home>/sites/all/modules directory. For example, placing your codebase backup in <drupal home>/modules/civicrm.bak... will cause errors (Drupal executes any *.module files that are found in the modules or sites/all/modules directory tree).

7. Unpack the latest package and verify permissions

8. Run the Upgrade script

This step is required for ALL upgrades.

Support for MySQL versions 4.0 and 4.1 has been discontinued. This means that you may encounter various issues and/or unexpected behavior if you attempt to run CiviCRM under these versions, and the CiviCRM engineering team will not provide support for debugging or resolving these issues. You are strongly encouraged to upgrade to the current generally available release of MySQL.

* Point your web browser to the following URL (you should already be logged in to Drupal with administrator-level permissions):

9. Verify and Update Resource URL Settings

If you are running this installation in a different directory from your previous version you may need to update the configured CiviCRM Resource URL (Missing icons and images, as well as problems with javascript functions and stylesheets are all symptoms that this setting needs to be updated.)

10. Enable Components

If you plan on using the new CiviCase component, or any components that you weren't using in the prior version (e.g. CiviPledge or CiviGrant for grant management) - you'll need to enable these component(s):

If you have been using Cases in 2.2 and / or want to start using the CiviCase component, you will also need to complete additional configuration steps. Learn more...

11. Re-enable compatible CiviCRM integration / extension modules

Administer » Site Building » Modules

Go through your list of CiviCRM integration / extension modules and confirm compatibility with the new release if applicable. (If you've downloaded the module from Drupal.org - check the module's page for compatibility information.)

Re-enable all compatible modules by re-checking the Enabled box. You may want to do this "one at a time" if you're unsure of compatibility.

12. Review and Update Drupal Permissions Settings

13. Clear Views' cache (for sites using Views 2 integration)

14. Restore CiviCRM as the Drupal homepage if appropriate

If you changed the default Drupal homepage from civicrm to node in step 3 above, you need to restore civicrm as the homepage. You can do this by navigating to:
Administer » Site Configuration » Site Information
then change the Default front page to civicrm, and click Save configuration.

NB: As mentioned in 3 above, there are a variety of modules that may affect the Drupal homepage. Consult the appropriate module's documentation if you are using them to set the homepage to civicrm for the administrative action required to change your site's homepage back to CiviCRM.

15. Put the Site Online (for production site upgrades)

16. Review background scripts

If you run a script to send out automated membership renewals it will have been removed from civicrm/bin/UpdateMembershipRecord.php. You will need to put it back. More info on the membership types page

If you run an IMAP/POP-based CiviMail return channel , the required cron script changed from civicrm/bin/CiviMailProcessor.php to civicrm/bin/EmailProcessor.php. You need to update it.

In general, it is prudent to review the Command-line Script Configuration

Upgrade Trouble-shooting

Check this section for answers to upgrade problems. If your problem isn't addressed here, check out the Installation and Configuration Trouble-shooting page for additional resources.

Version information missing in civicrm database

Try running a query like this: 'UPDATE civicrm_domain SET version = '2.2.9' WHERE id = 1;'

Then try invoking the upgrade script again with your browser.

Non-recoverable error: Unknown column 'is_deleted' in 'field list', 1054 

Another Drupal module is accessing the database and the update process is being blocked. Disable any modules that interact or rely on CiviCRM, such as RealName. Perform the update, then enable those modules again.

Page Not Found error

if you get this error when trying to upgrade the database in step 7, you most likely disabled CiviCRM in step 3. Here's how to fix it and get back on track. In short, you have to restore the original version of civicrm, re-enable the module, and then replace the old files with the new.

Reset Your User Session

If you are getting foreign key constraint errors when trying to add or modify records, you may need to reset your user session.

Verify and Update Base Directory and Base URL Settings in the Database

If you are seeing problems with missing images or page styling, you may need to adjust the Base Directory and Base URL Settings in the database. You can do this from:
Administer CiviCRM » Configure raquo; Update Directory Path and URL

Verify and Update Configuration Settings File

CiviCRM in versions 2.2 stores most configuration settings in the database. However values needed to load the code and database are stored in the settings file and may need to be updated prior to beginning the upgrade process if you are upgrading a copy of your working 2.2 site:

<drupal home>/sites/xxx/civicrm.settings.php (usually /sites/default/civicrm.settings.php).

A fatal error appears when I try to load a CiviCRM page.

Fatal error: civicrm_initialize() [CRM:function.require]: Failed opening
required 'CRM/Core/Config.php' (include_path='.:/opt/local/lib/php')
in <drupal root>/modules/civicrm/modules/civicrm.module on line 206

This error likely indicates that the new CiviCRM configuration file is not in the expected location or that the $civicrm_root setting is incorrect. See step 3 above.

Foreign Key Errors or Warnings During the Database Upgrade

Foreign keys may have been assigned different names on some installations. Also, different versions of MySQL handle the dropping and adding of constraint checks differently. Try this procedure or this procedure (on the forum) to reload your data into a new 3.4 database structure if you are having this type of issue with upgrading your database.

Upgrade script fails with fatal database-related errors OR reports "Database check failed"

Download and run Database Troubleshooting Tools to test the current state of the database and provides a diagnosis. The tools suite also includes a repair facility.

Calendar widget doesn't work (throws a Javascript error), and/or CiviMail scripts for open tracking, SOAP authentication, etc. don't function.

If your CiviCRM codebase is NOT located in either <drupal root>/modules/civicrm or <drupal root>/sites/all/modules (i.e. you are using a symlink from there to your codebase) - you will need to create a local file in the top-level directory of your codebase which points to the location of your drupal sites directory.

// Create a new file - settings_location.php
// Enter the following code (substitute the actual location of your
// <drupal root>/sites directory)
<?php
define( 'CIVICRM_CONFDIR', '/home/lobo/public_html/drupal/sites' );
?>

Access Forbidden (403) Error After Upgrade

This may be caused by directory permission settings. Make sure your <drupal home>/files/civicrm directory is set with chmod a+rwx -R
If you're still getting this error and have clean URLs enabled, try disabling clean URLS (Drupal >> admin >> settings) prior to running the session reset and cleanup. Then re-enable clean URLs.

Screen grays out and a camera icon appears whenever  you click any link in CiviCRM

This error is caused by a known problem in the Drupal Lightbox2 module.  Either disable the module in Administer » Site Building » Modules or upgrade to the dev version of the Lightbox2 (dated July 2009 or later) that fixes this issue.

Reset config_backend

Having strange problems with Administrative settings forms after upgrade? Try this: http://wiki.civicrm.org/confluence/pages/viewpage.action?pageId=2981949 or try deleting all files in [yoursite]/sites/default/files/civicrm/templates_c/

UpdateMembershipRecord.php won't run after upgrading from prior versions

Double check that there is a Membership Status Rule called "Deceased" and that it is active in Administer » CiviMember » Membership Status Rules. The solution is described in this forum thread.

The menus are wrong, the admin dashboard does not have the correct links and settings, or get an error with CRM_Core_Invoke::require_once()

You can re-build the menu/admin dashboard by visiting the following url - (http:///civicrm/menu/rebuild?reset=1 (http://%3cdomain%3e/civicrm/menu/rebuild?reset=1)

Version information missing in civicrm database error

Try running a query like this: 'UPDATE civicrm_domain SET version = '2.2.9' WHERE id = 1;'

Then try invoking the upgrade script again with your browser.

CiviMail mailings stuck in "Running" / CiviMail cron task fails to execute

Permission requirements for the user who executes the CiviMail cron task may be more stringent following the upgrade. Double check that the user has sufficient permissions to access the mailings and contact records.