Table of Contents
Step-by-step Upgrade Procedures1. Download the most recent CiviCRM Package
2. If Using Localization download the latest version of the localisation filesSee the CiviCRM Localisation page about how to install files for running CiviCRM in languages other than American English. 3. 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. 4. Ensure that CiviCRM is not your Drupal homepageDue 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:
5. 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.
6. Backup your CiviCRM databaseRefer to the MySQL reference manual or the phpMyAdmin documentation if you need information on backing up your database. Note that not all versions of mysql or phpmyadmin export triggers or stored procedures by default. 7. Backup and then delete all previous version code filesCiviCRM 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.
8. Unpack the latest package and verify permissions
9. Run the Upgrade scriptThis step is required for ALL upgrades.
* Point your web browser to the following URL (you should already be logged in to Drupal with administrator-level permissions):
10. Verify and Update Resource URL SettingsIf 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.)
Note: if your site uses https, you must have Force Secure URLs enabled at <example.com>/civicrm/admin/setting/url?reset=1 If not your images will be stored with an https:// protocol, but then CiviCRM removes the s when it tries to display them. Choosing Force Secure URLs is sensible anyway, if you are able to use https. 11. Enable ComponentsIf 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... 12. Re-enable compatible CiviCRM integration / extension modulesAdminister » 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. 13. Review and Update Drupal Permissions Settings
14. Clear Views' cache (for sites using Views 2 integration)
15. Restore CiviCRM as the Drupal homepage if appropriateIf 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:
16. Put the Site Online (for production site upgrades)
17. Review background scriptsSystem Administrators: All CiviCRM-related cron jobs will stop working as soon as any site is upgraded to 4.1. Cron jobs will need to be reconfigured using the new Scheduled Jobs method. In the previous versions, background jobs were handled with individual scripts. For reference, you may also want to refer to the Command-line Script Configuration to help you migrate your settings from the old scripts to the new centralized Scheduled Jobs method. Upgrade Trouble-shootingCheck 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 databaseTry 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', 1054Another 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 errorif 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 SessionIf 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 DatabaseIf 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: Verify and Update Configuration Settings FileCiviCRM 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.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 UpgradeForeign 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. Access Forbidden (403) Error After UpgradeThis may be caused by directory permission settings. Make sure your <drupal home>/files/civicrm directory is set with chmod a+rwx -R Screen grays out and a camera icon appears whenever you click any link in CiviCRMThis 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_backendHaving 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 versionsDouble 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 errorTry 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 executePermission 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. All you see is the word "Array" when you load /civicrm/upgrade?reset=1The CIVICRM_UF parameter is not correctly changed to "Drupal6" (step 6 above). Be sure you changed the actual parameter and not the example in the comments. After clicking "Upgrade Now", upgrade freezes with "[ ]" message (Firefox)This may be a compatibility issue with certain releases of Firefox. The issue has appeared intermittently and has not been reliably reproduced. If you encounter it, please report details at CRM-11386; to continue with the upgrade, you can work-around the issue by upgrading Firefox or using a different web browser. |
Étiquette