How to Upgrade Magento through SSH

In this tutorial you will learn how to upgrade Magento using SSH (Secure Shell) and a staging site.

IMPORTANT: Always create a backup of your store (files and database) before you attempt to upgrade Magento.

Prerequisites

  • SSH access and basic Linux administration skills
  • PHP memory_limit should be at least 256 MB
  • PHP max_execution_time and webserver connection timeout high enough

Create backups

Before we start doing anything to our Magento installation we need to create a full backup of the files and database. If anything goes wrong, at least we can roll back to how things were.

Backup files

The first thing we will do is to create an archive of our entire code base. You can either do this through your control panel such as cPanel, using the built-in File Manager, or through SSH.

cpanel-compress

Create archive through cPanel File Manager

In this example we are creating a GZipped Tar archive from the public_html directory. The same can be accomplished in SSH with the following commands:

tar -zcf public_html.tar.gz public_html

Backup database

Most control panels offers a web interface for creating a database backup, or you can use a tool such as phpMyAdmin or simply the following SSH command:

mysqldump -u database_username -p database_name > database_name.sql

This will save a database dump of database_name to a file database_name.sql.

Create a staging domain

We do not want to apply the upgrade directly to our live production site. Magento upgrades, especially in the past, were notoriously known to fail, so we first want to test that everything works as planned in a safe and isolated environment. Later we will simply swap the live site with the upgraded version.

In this example, we use a subdomain (staging.ourmagentosite.com) for our staging site. Exactly how to create the subdomain depends on which control panel you are using, but with cPanel just go to the Sub Domains section and type in the information as below.

cpanel-create-subdomain

Create subdomain in cPanel

Once the subdomain has been set up we can proceed to the next step.

Create new database

We will now create a new database for our staging site, which will ultimately be used for the upgrade. Again, this is straight-forward in cPanel using the MySQL Database Wizard. I name my database %username%_staging. Next, we need to import the database backup we created in the previous step. Either use a tool such as phpMyAdmin or this SSH command:

mysql -u database_username -p staging_database_name < database_name.sql

Remember to change the username and database name according to what you created. We should also change the Base URL in the database to reflect the staging domain to not interfere with the live site. Here is the SQL command for that:


use staging_database_name;
UPDATE core_config_data SET value='http://staging.ourmagentosite.com/' WHERE PATH LIKE '%base_url';

Remember to include the trailing /.

At this point, our new database is ready for the upgrade. Lets move on to the next step.

Extract file backup to staging domain

Now, extract the content of the backup archive created previously into the directory for the staging domain.

  1. Use the extract functionality built into the cPanel File Manager, or use this SSH command to extract a GZipped Tar archive:tar -zxf public_html.tar.gzIt will extract the content to the current working directory, so you might want to move it to the document root for the staging domain first.
  2. Edit the app/etc/local.xml configuration file, and change the database details to point to the new database created.
  3. In the same file, locate the node <initStatements> and add ; SET FOREIGN_KEY_CHECKS=0; SET UNIQUE_CHECKS=0;
    This will turn off the integrity checks during the upgrade (we will turn it back on afterwards).
  4. Delete the downloader directory inside the Magento directory (on the staging site), and replace it with the same directory from the clean installation package for Magento (same version). Release archive is available from here: http://www.magentocommerce.com/download. This is very important because some of the files inside the downloader directory contains path information about your site, and we don’t what it to use the path to the production site. If you are upgrading from version 1.4.2 or later it is only necessary to delete the file downloader/pearlib/pear.ini.
  5. Delete the content of var/cache/

We are now ready to start the upgrade.

The upgrade

[From Magento 1.4.1 or older]

If you are running Magento version 1.4.1 or older, the upgrade will be done in two steps. Magento 1.4.2 contains significant database schema changes as well as a new PEAR downloader, so we will first upgrade to 1.4.2 before we can move on to the latest version.

Run the following SSH commands in sequence:

./pear mage-setup .
./pear clear-cache
./pear upgrade -f magento-core/Mage_All_Latest-stable
chmod 550 ./mage
./mage mage-setup .

Go to the staging URL to trigger the database update. It will happen in the background so you will just see a white page loading, but DO NOT leave the page or close the browser as it will interrupt the upgrade. This can take several minutes. Once the page has finished loading, hopefully without any errors, log into the admin panel and verify that it says Magento 1.4.2.0 in the footer.

[From Magento 1.4.2.0 or later]

Run the following SSH commands in sequence:

./mage sync
./mage sync-pear
./mage config-set preferred_state stable
./mage install http://connect20.magentocommerce.com/community Mage_All_Latest --force
./mage upgrade-all --force

Go to the staging URL to trigger the database update. It will happen in the background so you will just see a white page loading, but DO NOT leave the page or close the browser as it will interrupt the upgrade. This can take several minutes. Once the page has finished loading, hopefully without any errors, log into the admin panel and verify that it says Magento 1.4.2.0 in the footer.

Congratulations! You have now successfully upgraded your Magento store.

You can now revert the changes you made to <initStatements> in app/etc/local.xml.

Troubleshooting

Sometimes you might get errors during the database upgrade. Mostly, these errors are caused by incompatibilities with the theme or some custom code extension.  If the problem is caused by a paid extension, you can contact the developer to see if they have an upgrade available. If the error is caused by a problem with the theme, you can try to find out from the stack trace which file is causing the error and then replace it with the default file from the base template.

Here is an example of a fairly common one:

Error: Invalid method Mage_Page_Block_Template_Links::addLinkBlock(….)

In this case, the template has an override for app/design/frontend/base/default/layout/wishlist.xml, which uses deprecated markup. Replace the file with the one from the base package to solve the problem.

Like This Post? Share It

Leave a Reply

Your email address will not be published. Required fields are marked *