Saturday, August 28, 2010

SugarCRM Server Migrations Demystified

Perhaps one of the more interesting administrative tasks you might be required to undertake as a SugarCRM administrator is that of moving your installation from one server to another.  Your reason for needing to do this will likely relate to the retirement of the current server or perhaps simply moving from a hosted environment to an in house deployment.

Regardless, what makes the task interesting is the perceived complexity one might face in accomplishing the task. However, there is no reason to be nervous or worry.  Many of the potential challenges can be attributed to a handful of issues, mostly related to system configuration.

Let us begin with the most common issue: PHP configuration.

It is unlikely that the software configuration of the new server is an exact match of the system from which you are moving away.  This may seem like a minor issue, but in reality, this is the most common oversight in these type of operations.  To avoid the frustrations (and lost time) such an oversight might cause, you should first check the version of PHP and configuration (PHP.INI) on the new server and make sure that it is compatible with the version of SugarCRM you are currently using.  

A list of compatible versions of PHP, per SugarCRM version, is available on the SugarCRM web site.  Your findings might require you to either downgrade or upgrade the version of PHP on the new server prior to migrating the instance.

Often times administrators get themselves into trouble because in addition to migrating the instance to a new server, they also want to simultaneously upgrade SugarCRM to its most recent version.

Regardless of whether or not you have a need to upgrade SugarCRM as part of this process, the steps that should be followed to perform the migration from one server to another are:

1. Check new server configuration (and adjust if necessary) 
2. Copy SugarCRM program files from old server to new server 
3. Copy SugarCRM database from old server to new server
4. Modify SugarCRM's config.php file on the new server to update site_url and database settings

If you have a need to upgrade, it usually best to perform the upgrade after successfully migrating the instance to the new server.  Not doing so often leads to a number of problems and convoluted solutions that could have easily been avoided.

It is worth noting that some actions can also lead you into problems that might result in data loss, hence the importance of avoiding these traps. 

Here is a good example. 

Suppose your original server is running PHP version 4.4.x and SugarCRM version 5.0. You wish to move it to a new server that has PHP version 5.3 installed. At the same time, you would like to update SugarCRM to version 6.0.1. 

The problem with this scenario is that we can't simply copy it from the old server to the new and expect things to work. Version 5.0 of SugarCRM does not support PHP version 5.3, thus, would not function properly on the new server even if all files were copied correctly. Conversely, SugarCRM version 6.0.1 does not support version 4.4.x of PHP, so we also cannot simply upgrade SugarCRM on the old server as is without encountering other problems.

Many administrators opt for what seems like the simplest solution to the problem: install a fresh instance of SugarCRM 6.0.1 on the new server and then import the data from 5.0 or somehow try to connect the new instance of SugarCRM to the old database. I personally strongly advice against this technique.

For one, it requires intimate knowledge of SugarCRM in order to obtain a decent level of success.  In addition, it exposes you to potential loss of data, which is never a good thing. Equally important, if your system has a lot of customizations, there is a chance you might lose some or all of them, or they may not function as expected. In short, do not do this. 

The proper way of handling this is to find a common denominator between the two versions of SugarCRM, that is, find a version of PHP that is common to both.  In this case, reviewing the list of compatible versions tells us that PHP versions 5.2.1 - 5.2.5 are compatible with both.

Based on that information we can then downgrade the version of PHP on the new server to a version within that series and proceed to move our instance from the old server to the previously outlined steps. Once the move is complete, we can then upgrade SugarCRM to version 6.0.1 and if we like, we can also proceed to upgrade PHP to its original version of 5.3.

Of course, we could also do it the other way around and rather than downgrading PHP on the new server, we could upgrade PHP on the old server, perform the upgrade of SugarCRM and then move it to the new server. The potential problem here is that you might also need to upgrade other software, more specifically, MySQL, as SugarCRM 5.0 supports MySQL 4.1.x, but SugarCRM 6.x does not. 

The bottom line: always check the system configuration and SugarCRM software requirements before you begin!


  1. We lost our SugarCRM server and now I am installing to a new machine. I have the mysql db. The issue is I want to install 6.5, was on 5.2, and I want to use MS SQL instead. Any hints as to how best move the MySql data into the new version and into SQL Server?

    1. You are in for quite a bit of work.

      I would first get the instance running with 5.2 and MySQL. Once you have that squared away, upgrade it, while still on MySQL.

      Whatever you do, do not switch over to MS-SQL before upgrading.

      Once you have a working 6.5 install, then you can make the switch. Note that you'll have to make that switch manually, as Sugar doesn't provide a facility for that process. Talend or other similar ETL solution should help you accomplish that task.

  2. When I try to install SugarCRM afresh on the remote live server (Linux),it ends up with the error that says something to the effect "passwords provided do not match". also mentioning about line 278 in mysqlimanager.php. This is even after trying a variety of values with parameters in config file. I visited all the blogs with no help to overcome the isue. I shall be thankful if you could help me in solving this. Best Regards

    1. I don't know of any bugs or problems within Sugar itself that would cause that. Either the SQL address or user/password info is not correct.

  3. i have migrated sugar crm as suggested on the official documentation to a windows sbs server. It seems to be working as intended on the new server but the email functionality seems to be broken. The email address is also running from exchange. Is there any way of fixing this?

    1. I am not sure which section of the documentation you are referring to, nor do I understand the problem at hand.

      Are you getting an error message? How do you know it is broken? Have you checked the sugarcrm.log file to see if it offers any clues?

  4. In the old days, we had something called "backwards compatibility". What happened to that?


Your comments, feedback and suggestions are welcome, but please refrain from using offensive language and/or berating others. Thank you in advance.