by Alan Barber – Senior Magento Developer

I’ve been seeing a lot of questions about upgrading Magento recently, but not in any one-place with consolidated answers. To that end, I’ve created a how-to guide below for Magento upgrades. I’ve done 15 Magento upgrades in the past year and have learned from experience what to expect. At the most abstract level, these are the steps for upgrading a Magento installation:

1. Install a fresh version the magento file tree (the version you are trying to upgrade to)

2. Run the installer from this file tree on-top of the outdated database (thereby upgrading the database)

3. Move over themes and custom extensions from the old version to the current version.

For more information about upgrading Magento and Magento programming services, or to get Magento help now, call us at 303.473.4400 or fill out the form below to speak with a real person now.

***Note*** The most recent versions of magento offer the “mage” and “pear” upgrade commands, but this guide assumes you do not have access to these utilities.

Part I : Install the newest version of Magento

The first step I take in any upgrade is to install the most recent version of the magento file tree. I will generally put this in a /fresh/ folder inside my magento installation. See this url for information on installing magento: http://www.magentocommerce.com/wiki/groups/227/installing_magento_via_shell_ssh. After uploading/unzipping the most recent version of magento, we should have the standard file tree in /fresh/ on our server /magento_root /fresh /app /js /skin /var If we navigate to {mydomain}/fresh/ in the browser we should be prompted by the magento installer at /fresh/download/to pick a database to install the most recent version to.

Part II : Upgrade the Magento Database

The next step in the process is forcing magento to change the database structure of an older version to the newer schema. Before I describe the specific steps involved in this, I think it is worth discussing the process by which magento maintains its database structure:

Some Background

Essentially, every module in magento (and by module I mean the list of folders found inside app/code/core/Mage/) which utilizes the database keeps track of the version of its database schema. For the purposes of this example I will be referring to Mage/Sales (found in app/code/core/Mage/Sales).Inside the sales module you will see a directory structure like the following:

You will notice the “sql” folder —- This is the folder that contains instructions for either installing or upgrading the portions of the database this module interacts with. Opening up “sql” we see the following structure:

You will notice that the sql folder contains a sub folder named sales_setup which then has php files for a fresh install (in this case version 1.6) as well as upgrades from version to version. I have not shown all of the upgrade scripts in this screen shot, but this module contains scripts to upgrade from version .7.0.0 to 1.6.0.3.What happens every time magento loads its configuration xml is it checks the version number for “sales_setup” in table ‘core_resource‘ with the current version of the module (listed in {module}/etc/config.xml (ie: app/code/core/Mage/Sales/etc/config.xml))

If the version number in ‘core_resource‘ differs from that found in <config><modules><{module_name}><version> magento knows to look for sql upgrades in the folder {module_name}/sql/{core_resource_code} (ie : Mage/Sales/sql/sales_setup)So take a situation where sales_setup is version 1.5.9.9 in `core_resource` but the module version in 1.6.0.3 in config.xml. Magento will look for a file in Sales/sql/sales_setup/ that begins with the prefix mysql4-upgrade-1.5.9.9- or upgrade-1.5.9.9-If a file with this prefix exists, magento knows that it needs to update the database. In this case, the actual file name is mysql4-upgrade-1.5.9.9-1.6.0.0 Magento will run this script and then re-evaluate whether to continue looking for upgrade scripts. The second piece to the file name is 1.6.0.0, which is still < 1.6.0.3 so magento will look for another upgrade script. As of version 1.6, there are 3 additional upgrade scripts upgrade-1.6.0.0-1.6.0.1.php upgrade-1.6.0.1-1.6.0.2.php upgrade-1.6.0.2-1.6.0.3.php So in the case of “Sales” there are upgrade scripts up to 1.6.0.3. However, this will not necessarily be the case for all modules.Some modules may not change their db structure from version to version. In other words, while a module’s version may change (In config.xml) its database structure may remain the same. That can seem complicated, so lets break it down: Magento notices a difference between the version number in ‘core_resource‘ and config.xml Magento then scans {module}/sql/{module_code} for upgrade scripts If magento finds an upgrade script starting at the version listed in ‘core_resource‘ it will upgrade that script. Magento will continue to run upgrade scripts while: a. The version in ‘core_resource’ < config.xml b. Sql upgrade scripts are available for the current version This is a very powerful setup, and is exactly what happens when we initiate a magento database upgrade.

Upgrading the Database

Now that you (hopefully) understand the process by which core modules update their database schema, I will outline how to initiate this process. Assuming you have the version of magento you are trying to upgrade to installed in /fresh/ Do the following:

1. Perform a mysqldump of your current magento database and import that dump into a dev database

2. Navigate in your browser to /fresh/

3. You should be redirected to the installer at /fresh/downloader

4. Fill out the relevant information

5. At step 3, enter the database information for the development db copy you created in step 1

6. Click “Continue”

7. Magento is now upgrading your database. Depending on the amount of data in the database, and the version you are upgrading to, this process could take anywhere from 10 minutes to several hours. Remember that magento is having to run up to 60 upgrade scripts for multiple modules to make this process happen. a. If you have access to mysql, you can run the command SHOW PROCESSLIST; and you should see update sql commands happening

8. Completion. Hopefully the installer finishes successfully. Your database in now updated! …If the installer ran into a problem, you have a few options you can try: a. Run the database repair tool. I will not go into detail on how this works, but you can take a look at this url: http://www.magentocommerce.com/wiki/1_-_installation_and_configuration/db-repair-tool b. Hack the upgrade scripts. If magento is bombing out on a specific upgrade script, you can try playing around with commenting code out in these files or manually executing some sql commands. This is rather advanced, and I’m not going to go into it in this document.

9. Change the base urls for testing a. In the table ‘core_config_data‘ you will need to update web_secure_base_url and web_unsecure_base_url to reflect the /fresh/in the url.

Part III: Magento Themes and Magento Extensions

At this point, you should have a fresh, recent version of magento located at /fresh/ linked to an upgraded,recent database. Now comes the dirty part. There are no magic utilities for upgrading your site’s design and custom extensions to the most recent version…hopefully you’ve had a designer and developer who methodically thought out their code and followed magento’s design pattern (using data models, avoiding raw sql queries, etc). The general process for transporting extensions is the following. I’m assuming you understand some bash commands: /magento_root/ refers to your old version /fresh/ refers to your new version

Moving Magento Extensions

$ cp -R /magento/app/code/local/* /fresh/app/code/local $ cp -R /magento/app/code/community/* /fresh/app/code/community/ $ cp -R /magento/app/etc/modules /fresh/app/etc/modules

Moving the Magento Theme

Theme: $ cp -R /magento/app/design/frontend/{package}/{theme} /fresh/app/design/frontend/{package}/{theme} $ cp -R /magento/skin/frontend/{package}/{theme} /fresh/skin/frontend/{package}/{theme} If you have custom extensions that modify the admin theme, you will need to move individual layout.xml files and template.phtml files from: /magento/app/design/adminhtml/default/default to /fresh/app/design/adminthml/default/default and also possibly skin from /magento/skin/frontend/adminhtml/{package}/{theme} /fresh/skin/frontend/adminthml/{package}/{theme} Depending on what you had installed, you may also need to move information from: /magento/lib to /fresh/lib /magento/js to /fresh/js

Moving media

You will definitely need to move your store’s media from folder to folder: $ cp -R /magento/media/* /fresh/media $ chmod -R 777 /fresh/media

Testing

Hopefully at this point /fresh/ is now looking a lot like /magento… if that’s the case, you are done moving your theme over. I always encourage a large amount of testing…I always make sure to look at the following pages: /index.php /customer/account a product page a category page cart page (with items) checkout page I also make sure to always checkout with all the payment methods on my /fresh at this point. If you have moved your theme to version 1.6, you may need to reorganize some of your template/checkout and template/customer files as magento has added the “persistent” shopping feature, and changed the template folder hierarchy for these 2 modules (some of their template files are now under template/persistent.

Encryption Key

Magento stores an encryption salt in app/etc/local.xml. You need to make sure to copy this encryption key to your new local.xml located in /fresh/app/etc/local.xml. If you do not move this key, you may experience problems with payment gateway credentials and shipping credentials. If you copy your encryption key and still experience these problems, you may need to re-enter your payment and shipping credentials

Pushing Magento Changes Live

Assuming you have your now-complete upgrade in /fresh/ you can move your change live by doing the following (assuming you have a directory structure like this): /public_html /fresh $ cd public_html/.. $ mv public_html/fresh ./new_html $ mv public_html old_html $ mv new_html public_html You will also need to change your base url’s in ‘core_config_data‘ one more time to remove the /fresh/ from them. Hopefully this document can help you the next time you need to upgrade your magento store. I invariably run into at least one obscure problem every-time I perform an upgrade, and in those situations googling and self-resourcing are always your best courses of action. One other point I’d like to make is that I almost always end up upgrading the database twice. The first time I upgrade it, I am doing it to make sure that when I’m ready to push live I know that my upgrade process will work. I then move over the theme and extensions. By the time I am ready to push the upgrade live, the database I upgraded is out of date (new orders have come in, the client has usually created new products, etc). So I then put a maintenance page up and upgrade the database one more time. Alan Barber is a Senior Magento Developer at Customer Paradigm who specializes in systems architecture and application troubleshooting.

To have Customer Paradigm contact you about upgrading Magento, please fill out the contact form below or call us at 303.473.4400.