SugarCRM Upgrade Instructions

Upgrading Sugar

For Sugar Ultimate, Sugar Enterprise, Sugar Corporate, and Sugar Professional, download the Upgrade zip file from the Sugar Support Portal at into your local machine.

Log into the Sugar application to use the Upgrade Wizard. Run a PHP script from the command line on the server where the Sugar instance is installed to use the Silent Upgrader.

CAUTION: It is strongly recommended that you run the upgrade process on a copy of your production system.

Compatibility matrix for upgrade

PHP version
5.2.1-5.2.6, 5.2.8-5.2.15, 5.2.17, 5.3.0 – 5.3.6


  • MySQL – 5.0x, 5.1
  • MSSQL – 2005, 2008
  • Oracle – 10g, 11g
  • (Oracle is supported only for Sugar Ultimate and Sugar Enterprise)

Operating systems

  • Windows: Sugar runs on any OS that runs PHP
  • Linux: Sugar runs on any OS that runs PHP
  • Mac: Sugar runs on any OS that runs PHP

Upgrade prerequisites

  • Backup your current Sugar directory and database before beginning the upgrade process.
  • Disable op-code caching before upgrading your Sugar installation if op-code caching is enabled in the PHP configuration file. You can enable it after the upgrade process is complete.
  • Increase the default value of the parameters listed below before you begin the upgrade process if you are using Zend Core 2.0:
    • Navigate to C:Program FilesZendCoreetcfastcgi.conf and increase the default value for ConnectionTimeout to 3000 seconds and RequestTimeout to 6000 seconds.
    • Navigate to the php.ini file and increase the default value of max_execution_time to 6000 seconds.
  • Perform the following for the large size of the upgrade files:
    1. Modify and save the value of Maximum upload size to 21000000 (20MB) in the Advanced section of the System Settings page of your current Sugar installation.
    2. Navigate to the php.ini file on your web server and configure the parameters listed below in the Advanced section of the System Settings page of your current Sugar installation:
      • Set post_max_size to at least 60MB
      • Set upload_max_filesize settings to at least 60MB
      • Set max_input_time to a large number
      • Set memory_limit to 256MB
      • Add the following to the web.config file, if your sustem is on IIS7 (since IIS 7 has a transfer size of 30 MB by default):
        <security><requestfiltering><requestlimits maxallowedcontentlength=”1000000000″></requestlimits></requestfiltering></security>
    3. Restart the web server and begin the upgrade process.
  • Ensure that LimitRequestBody is set to a large number or use the default value of 2GB if you are using an Apache web server and LimitRequestBody is set in the httpd.conf file. Restart Apache and begin the upgrade process.
  • Ensure that the webserver user has write permissions to the Sugar database. The upgrade to Sugar 6.5 will add and replace files in several locations including the Sugar root directory. The webserver user must have write permissions for the root folder and all sub-directories during the upgrade process.
  • The process of upgrading can take up to 30 minutes. Set the CGI script timeout to more than the default 300 seconds to ensure that the CGI application does not time out if you are using the IIS web server.
  • Save PHP files for customized modules (for example, accounts.php) in the Customs directory and not within the main module. Existing customizations may be overridden by changes in Sugar 6.5 during upgrade.

Upgrade considerations

The Dynamic Teams feature requires some database schema changes across all modules as part of the upgrade process. For larger databases, this operation can take some time to complete.

Follow the steps listed below to ensure a smooth upgrade process:

  1. Test your upgrade on a development instance instead of the production instance.
  2. Use the Silent Upgrade method through the command line interface to conduct the upgrade instead of the Upgrade Wizard inside the application if your database contains more than 10000 records per table.
  3. Log into the application as an Administrator and use the Repair option to repair and rebuild the database after the upgrade is complete.

Using the Upgrade Wizard

The Upgrade Wizard provides a quick way to upgrade to the latest version of the Sugar application. It includes critical upgrade logic as well as the SQL commands needed to upgrade the application.

Ensure that the config.php file for your installation, located in the Sugar root directory, is writable, before using the Upgrade Wizard.

Note: Manual upgrades by file replacements and running the upgrade SQL are not supported.

Follow the steps listed below to upgrade Sugar using the Sugar Upgrade Wizard:

  1. Download the appropriate Sugar Upgrade zip file from the Sugar website to your local machine. For example, download the SugarPro-Upgrade-6.4.x-to-6.5.0.zipfile to upgrade Sugar Professional from version 6.4.x to 6.5.0. Download the appropriate conversion file to convert to Sugar Professional or Sugar Enterprise.
  2. Log into your existing Sugar application as the administrator and click Admin on the right-hand corner of the page.
  3. Click Upgrade Wizard in the Systems panel of the Administration Home page.
    This displays the Upgrade Wizard page.
  4. Click Next.
    This displays the System Checks page. and Sugar begins the system check process. The Systems Check page indicates that there were no issues if the system check process completes successfully. Issues with file permissions, database, and server settings are listed on the page if the system check process encountered any problems.
  5. Click Next if the system check is successful.
    This displays the Upload an Upgrade page.
  6. Click Browse, and navigate to the location of the upgrade zip file and select it.
    The path to the file displays in the Upload an upgrade field.
  7. Click Upload Upgrade to upload the package to the Sugar application.
    The system uploads the package and displays it on the page. Use the Delete Package button to remove the package if necessary.
  8. Click Next.
    This displays the Preflight Check page.
    Click Show Schema Change Script to view differences in the Sugar databases schema between your current and new Sugar versions.
    By default, the Upgrade Wizard Runs SQL option is selected as the database update method. SelectManual SQL Queries from the Database Update Method drop-down list and select the Check when SQL has been manually run box, if you ran the SQL queries manually.
  9. Click Recheck to rerun Preflight Check. Click Next to skip this step.
    This displays the Commit Upgrade page.
    You can also click Show to see a list of files that were copied and the rebuilt results. Optionally, you can view skipped queries.
  10. Click Next.
    During the upgrade process, Sugar performs a three-way merge between the customized instance on old version, default instance on old version, and default instance on new version. This three-way merge adds any fields that have been added to the default module layouts in the new version to the corresponding module layouts in the existing version, if the module layouts in the old version were not customized through Studio (or in the appropriate upgrade-safe way) prior to the upgrade. The three-way merge also changes the placement of fields in non-Studio-customized module layouts to match the placement in the default module layouts.
    Sugar displays the Confirm Layouts page as Step 5 of the upgrade process if the existing module layouts have been customized, and there are changes to the default fields and field placement in the new module layouts.
    The Confirm Layouts page lists the module layouts that have changed in the new version. The administrator has the option of applying the changes to the existing module layouts. By default, all of the listed module layouts are selected to be merged during the upgrade.
    For example, in 6.1.0, Sugar added the Assigned To fields to the default Detail View and Edit View layouts for Notes and for Email Templates. If the instance being upgraded has a customized EditView layout for Notes, but no customized layouts for Email Templates, the following will occur during the upgrade:
    • The Confirm Layouts page appears as Step 5 in the Upgrade Wizard.
    • The Confirm Layouts page displays the Notes module with the EditView and DetailView layouts. The Email Templates layouts do not display on the Confirm Layouts page because the existing layouts were not customized.
    • The Administrator has the option of choosing to merge the changes in the Notes module with the existing customized EditView layout.
  11. Uncheck the module if you do not want to add the new fields to a module.
  12. Click Next.
    This displays a message confirming that the layouts were successfully merged (if you chose to update your modules).
  13. Click Next.
  14. The Debrief page confirms the upgrade installation. Complete the steps for manual merging of files or running SQL queries now.
  15. Click Done.
    This displays the Home page indicating that the upgrade is complete.
  16. Click Repair and select the Rebuild Relationships andRebuild Extensions options in the Systems panel of the Administration Home page.
    For more information, see Repair.
  17. Manually merge the files by extracting the skipped file from the patch zip file if you unchecked any files to prevent the Upgrade Wizard from overwriting them. Merge the file installed in the Sugar application directory.
    Note: Check the upgradeWizard.log file in the Sugar folder for information on unsuccessful Sugar upgrades.

Locking down the Upgrade Wizard

You can lock down the Upgrade Wizard to ensure that no user with administrative privileges can upgrade any of them, if you are managing multiple instances of the Sugar application and you want to maintain complete control over the Sugar instances.

Follow the steps listed below to lock down functions on the Administration page:

  1. Navigate to the config.php file in the Sugar root directory.
  2. Set the following parameter to true as below:
  3. Save the file.