I’ve been meaning to write an article on safely upgrading Magento for some time now, and with the release of Magento CE version 1.7.0 yesterday, April 24, 2011, now seems like a great time. These steps and commands are the actual ones I follow to upgrade client Magento sites, and I perform these core upgrades from the command line only. Please read through and understand all the steps before starting to follow them.

  1. Backup – This is the single most important step out of them all. You can not afford to be lazy and not backup both the database and webroot files prior to upgrading, it’s just too dangerous. I don’t care if you have a 100% mirrored development and staging environment and performed flawless upgrades to both, you must backup prior to upgrading production.
    • For the database you can make use of the built in backup found at System > Tools > Backups and then copy the resulting dumpfile from var/backups/ to somewhere outside of the webroot. Or you can perform a typical mysqldump.
    • For the files, use something like the following:
      $ tar czf example.com.120225.tar.gz html/

    Alright, now that we have our safety net, we can commence with the task of upgrading to the latest and greatest.

  2. Disable the Compiler – This can be done from the admin in System > Tools > Compilation, click ‘Disable’. Or, from the command line:
    $ php compiler.php disable
  3. No Cache – Disable caching, if enabled, from the admin in System > Cache Management: select all, action: disable.
  4. Protection – Next, we need to protect the site from being requested from any random visitor, as the first page request after upgrading will trigger any database updates, which can be time consuming, and must be allowed to complete properly. Note that before doing this, you must disable your Google Product Search account if used, along with any other no-downtime services. There are a few options for this:
    • One option is to restrict access to the site to your own IP address. Add the following to the root .htaccess:
      Order deny,allow
      Deny from all
      Allow from

      Where is your IP. I think this method is overkill, and I prefer not to deny the site entirely to important visitors, like GoogleBot. Also, the .htaccess file will most likely be replaced by the upgrade process anyways, rendering this method somewhat suspect.

    • Another option is to put the site into what I call a selective 503 mode, which I will add to this article at a later point
    • Another ideal way to perform the entire upgrade would be to replicate the file/database production environment, perform the upgrade in an area that only you had access to, verify and test the upgrade, and then point a symlink to the ‘new’ production. The details of this are not covered in this article.
  5. Like a Rock – Either from the Connect Manager, or the command line, ensure that the preferred state is set to ‘Stable’, so that you don’t accidentally upgrade to a beta release:
    $ ./mage config-set preferred_state stable
  6. List Upgrades – Verify which extensions are available for upgrade:
    $ ./mage list-upgrades
  7. Hold on to your butts – Upgrade the Magento core, and all available 3rd party extensions:
    $ ./mage upgrade-all --force
  8. Verify – Check for any packages that were not upgraded properly:
    $ ./mage list-upgrades

    Note that after a successful upgrade, the permissions for the mage script may be incorrect, so if you see ./mage: Permission denied, simply make the file executable, and then continue along:

    $ chmod +x mage
    $ ./mage list-upgrades
    • If you see ‘No upgrades available’, then everything upgraded successfully, and you can continue on to the next step.
    • Otherwise, rerun the upgrade-all command again. With the upgrade from 1.6.0 to 1.6.1 I had to run upgrade-all twice from the command line when testing on development and staging, but just once when doing production. Go figure:
      $ ./mage upgrade-all --force

      Before getting the all-clear from list-upgrades:

      $ ./mage list-upgrades
      No upgrades available
  9. Permissions – The permissions for the files are likely going to be incorrect at this point, so you may need to fix them with whatever method you typically use.
  10. Perform Database Migrations – From your browser, request the home page to run any database migrations.
    • If you see a 503 “Service Temporarily Unavailable” page, simply remove the maintenance.flag file from the webroot:
      $ rm maintenance.flag

      Request the home page to run any database migrations.

    • Clear the web services cache:
      $ ./mage clear-cache
    • Remove the IP restriction from .htaccess so the site is available again to the general public.
  11. Remove the Maintenance Flag – Remove the maintenance flag from the webroot if you have not already done so:
    $ rm maintenance.flag
  12. Compile & Cache – Re-enable the compile and caching, if used.
  13. Test – Test, test, test

In Case of Emergency

If the unthinkable happens and the upgrade fails, just stay calm, take a breath and replace the files/database with the backups you made in step 1:

$ tar xzf example.com.120225.tar.gz -C html/

$ gzcat 1325358690_db.gz | mysql -udbuser -p dbname

Published by Justin Stern

Justin is one of our co-founders, and is our resident overengineer. He likes to write developer tutorials and make black magic happen in our plugins. He thinks that writing code is a lot easier than writing words.


  1. Thanks for your manual. This way is good and I think for many users it will be like a breath of fresh air. I’d also suggest to try online service http://www.shopping-cart-migration.com, that I used. I’ve migrated my products, customers and even order history from my old store to a new one with no difficulties.

Hmm, looks like this article is quite old! Its content may be outdated, so comments are now closed.