Upgrading Magento

This quick guide will you upgrade to the latest version of Magento 1. Whilst these instructions make the process seem somewhat straightforward, you will likely encounter errors along the way on a modified store - and working through those errors will be a case of tackling each one at a time.

Prepare the upgrade

  1. Begin by putting the store into maintenance mode, so that you can create a backup point to restore to if the worst happens - and to prevent customers other users affecting the upgrade process
  2. Once mainenance mode is enabled, purge the log tables to reduce database bloat
  3. Then proceed to make a backup of your site using the store clone utility.

    clone_store.sh -f /microcloud/domains/example/domains/example.com/www -t /microcloud/domains/example/domains/example.com/___www_backup -d -m
    • The above command will clone the media directory, omit -m if you do not have the diskspace to clone your media directory
    • A database dump will be created and stored in ./var/db.sql
  4. Turn off all store caches in Cache Management as well as any other type of server cache (Varnish), you can also use MageRun to complete this,

     mr_examplecom cache:disable
  5. Temporarily disable your custom theme, the easiest way is to rename the directory

    mv app/design/frontend/yourthemename{,.backup}
  6. Disable all the custom extensions, the easiest way is to move all the .xml files in ./app/etc/modules to a new folder,

    mkdir app/etc/modules{,.disabled}
    find app/etc/modules -type f -not -name "Mage_*" -not -name "Enterprise_*" | while read FILE; do echo mv $FILE app/etc/modules.disabled/; done
  7. Flush the store cache completely,

    mr_examplecom cache:flush
  8. Delete pear.ini file in ./downloader/pearlib if it exists

    rm downloader/pearlib/pear.ini

At this point, it is really important to ensure the site is totally functional - so that you can understand the errors that occur as a result of disabling modules, versus the later errors you may see as a result of the upgrade

Launch the upgrade

The upgrade process changed after version 1.4.2; where in earlier releases pear was used to perform the upgrade, after 1.4.2, the new mage script is used in place of this.

So if you are running a version older than 1.4.2, you will need to upgrade to this version first - then repeat the upgrade process again for 1.4.2 to latest. Yes, you have to upgrade twice!

Upgrade to Magento 1.4.2

chmod +x pear
./pear mage-setup
./pear upgrade --force magento-core/Mage_All_Latest`

Then follow the steps outlined in running the upgrade.

Upgrade from Magento >1.4.2 to latest

Once you are on Magento 1.4.2 (or newer), you can now upgrade to the latest release,

chmod +x mage
./mage mage-setup
./mage upgrade http://connect20.magentocommerce.com/community Mage_All_Latest --force

Then follow the steps outlined in running the upgrade.

Running the upgrade

Once the upgrade process is complete, edit ./index.php and add enable developer mode and error printing.

Before the Mage::run line, add,

ini_set('display_errors', 1);

Now, the final steps are to complete the upgrade process via a web browser. An admin URL should be used to ensure no timeouts are hit during the process.

Eg. http://www.example.com/admin

Go to the admin page your browser and wait for the upgrade to complete. This process will take care of the database upgrade; it can take anywhere from a few minutes to a few hours, depending on the upgrade, and the size of your database.

If you are running the upgrade on a development environment, it is always good to note down when you start and finish the database update.

Final notes

  • Once the upgrade is complete, flush the store caches and make sure the database and files have been updated properly. Also make sure the site is totally functional (frontend, backend)
  • Re-enable your theme and your extensions and fix any errors you encounter
  • When everything is working, don’t forget to remove maintenance mode!
  • Magento changes the theme between releases to add security fixes and bug fixes, so when upgrading your store, consideration should be made to update your theme to match that of the latest version

Restoring your backup

Should the worst happen and you need to restore your backup, begin by restoring the files and database,

clone_store.sh -f /microcloud/domains/example/domains/example.com/___www_backup -t /microcloud/domains/example/domains/example.com/www -r -m

Then flush the caches as a precautionary measure,

mr_examplecom cache:flush