How to Upgrade Magento

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 192.168.1.1
     

     Where 192.168.1.1 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
   
   Success
   

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