Upgrade Magento Commerce (Cloud)

This information details how to upgrade Magento Commerce (Cloud) from any version after 2.0.4. If you’re currently using version 2.0.4, see Upgrade from version 2.0.4.

When you upgrade Magento Commerce (Cloud), you also upgrade with patches and available hotfixes as part of the magento-cloud-metapackage. Make sure you have auth.json in your project root folder if there isn’t one already.

Our upgrades are Composer driven. For more information on Composer, see Composer in Cloud.

Always apply and test a patch your local system in an active branch. You can push and test in an Integration environment prior to deploying across all environments.

We recommend that you first back up the database of the system you are upgrading. Use the following steps to back up your Integration, Staging, and Production environments.

Verify or set the ADMIN_EMAIL variable

The environment variable ADMIN_EMAIL is required for upgrading and patching. This email is used for sending password reset requests and verified during when updating Magento Commerce (Cloud). To set, see Add admin variables for Admin access.

Back up the database

Back up your integration system database and code:

Enter the following command to make a local backup of the remote database:
```
magento-cloud db:dump
```
Enter the following command to back up code and media:
```
php bin/magento setup:backup --code [--media]
```
You can optionally omit [--media] if you have a large number of static files that are already in source control.

Back up your staging or production system database:

SSH to the server.

Find the database login information:

php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"]))->database);'

Create a database dump:

mysqldump -h <database host> --user=<database user name> --password=<password> --single-transaction <database name> | gzip - > /tmp/database.sql.gz

Verify other changes

Verify other changes you’re going to submit to source control before you start the upgrade:

If you haven’t done so already, change to your project root directory.
Enter the following command:
```
git status
```
If there are changes you do not want to submit to source control, branch or stash them now.

Complete the upgrade

Change to your Magento base directory and enter the following command:

composer require magento/magento-cloud-metapackage <requiredversion> --no-update
composer update

For example, to upgrade to version 2.1.4:

composer require magento/magento-cloud-metapackage 2.1.4 --no-update
composer update

Add, commit, and push your changes to initiate a deployment:
```
git add -A
git commit -m "Upgrade"
git push origin <branch name>
```
git add -A is required to add all changed files to source control because of the way Composer marshals base packages. Both composer install and composer update marshal files from the base package (that is, magento/magento2-base and magento/magento2-ee-base) into the package root.

The files Composer marshals belong to the new version of Magento, to overwrite the outdated version of those same files. Currently, marshaling is disabled in Magento Commerce, so you must add the marshaled files to source control.
Wait for deployment to complete.
Verify your upgrade.

Verify your upgrade

This section discusses how to verify your upgrade and to troubleshoot any issues you might find.

To verify the upgrade in your integration, staging, or production system:

SSH to the server.
Enter the following command from your Magento root directory to verify the installed version:
```
php bin/magento --version
```

Verify and upgrade your extensions

You may need to upgrade any third-party extensions and modules that supports v2.2. We recommend working in a new Integration branch with your extensions disabled. Review your third-party extension and module pages in Marketplace or other company sites to verify support for Magento Commerce and Magento Commerce (Cloud) v2.2.

We recommend backing up your database prior to installing a number of extensions on your local and Integration environments.

Create a new branch on your local.
Disable your extensions as needed.
As available, download extension upgrades.
Install the upgrade on your local in the Git branch as documented by the third-party documentation.
Enable and test the extension locally.
Push the code to test in your Integration environment.
Push to Staging to test in a pre-production environment.

Include the extensions in your going live steps to Production only after fully upgrading Production to v2.2. We strongly recommend fully upgrading your Production environment before including upgraded extensions.

Troubleshoot your upgrade

In some cases, an error similar to the following displays when you try to access your storefront or the Magento Admin in a browser:

There has been an error processing your request
Exception printing is disabled by default for security reasons.
  Error log record number: <error number>

View error details on the server

To view the error in your integration system, SSH to the server and enter the following command:

vi /app/var/report/<error number>

Resolve the error

One possible error occurs when the deployment hook failed, and therefore the database has not yet been fully upgraded. If so, an error similar to the following is displayed:

a:4:{i:0;s:433:"Please upgrade your database: Run "bin/magento setup:upgrade" from the Magento root directory.
The following modules are outdated:
Magento_Sales schema: current version - 2.0.2, required version - 2.0.3

To resolve the error:

SSH to the server.
Examine the logs to determine the source of the issue.
After you fix the source of the issue, push the change to the server, which causes the upgrade to restart.

For example, on a local branch, enter the following commands:
```
git add -A && git commit -m "fixed deployment failure" && git push origin <branch name>
```