What is Magento Upgrade Compatibility Tool & How to Use It

Upgrading your store to the latest Magento version is necessary to keep up with the latest features and platform enhancements. Running a compatibility check is vital before the store upgrade not to run into potential issues after the procedure. The official Magento Upgrade Compatibility tool is what makes the process easier.

Adobe Commerce (Magento) is a leading eCommerce platform, well-known for its scalable and versatile range of features. The platform, owned by Adobe, releases regular version updates to help store owners meet the ever-changing requirements of the dynamic online selling industry. Magento works on improving the platform with every upgrade fixing hundreds of known issues and security loopholes and adding new features.

Magento 2 version upgrade can be a straightforward task when you are using the vanilla version of the platform. However, the real struggle is when you have plenty of custom modules, and development in your store and are not sure about their compatibility with the newer version. This can add an extra layer of complexity to the upgrade process.

Fortunately, the Magento Upgrade Compatibility tool is your friend here! The official tool by Adobe lets you find the potential incompatibilities in your system before upgrading, saving precious time and money.😃

In this article, we’ll explore everything about Magento Upgrade Compatibility Tool – What it is? How to Install it? How to Use it? And more.

Table of Contents

• What is Magento Upgrade Compatibility Tool?
  • Prerequisites of Magento Upgrade Compatibility Tool
• How to Download Magento Upgrade Compatibility Tool?
• Useful CLI Commands for Magento Upgrade Compatibility Tool
• Getting Ready for Magento Upgrade

What is Magento Upgrade Compatibility Tool?

Magento Upgrade Compatibility Tool is a command line offered by Adobe to help merchants check the compatibility of their store with the latest Magento version upgrade.

The tool analyzes the compatibility of the existing site’s functionalities, third-party extensions, and customizations against the new version of Magento. It lists the possible issues so that they can be fixed and avoided during the Magento upgrade process. Therefore, it saves merchants a lot of time and money by avoiding possible mistakes during the version upgrade process.

The Upgrade Compatibility Tool is only available for Adobe Commerce users.

Prerequisites of Magento Upgrade Compatibility Tool

It is essential to make sure your system has the resources required to download and install the Adobe Commerce Upgrade Compatibility Tool. The minimum requirements are:

Requirements	Constraints
PHP version	7.3 or above
Node.js	Node.js versions ^12.22.0, ^14.17.0, or >=16.0.0
Minimum RAM	Gigabytes
Operating System	Linux
Other Requirements	PCNTL and other PHP extensions

How to Download Magento Upgrade Compatibility Tool?

The Magento Upgrade Compatibility Tool can be installed anywhere on Linux OS; you do not necessarily need to install it where your Adobe Commerce instance is located.

Run the following command to download Magento Upgrade Compatibility Tool:

After successful installation, run the following chmod command to give executable permissions to the tool:

Useful CLI Commands for Magento Upgrade Compatibility Tool

Magento Upgrade Compatibility tool checks for potential incompatibility issues in Adobe Commerce against a specific version. Here are the CLI commands you can use with the tool.

Command	Description
upgrade:check	Runs the Upgrade Compatibility tool and analyzes all the modules installed in the system.
dbschema:diff	Finds and displays all the database schema differences between the current and new Adobe Commerce versions.
core:code:changes	Compares the current Adobe Commerce core code with a clean vanilla installation.
refactor	Automatically fixes a reduced set of issues.
graphql:compare	Introspects two GraphQL endpoints and compare their schemas.
list	Displays a list of all Upgrade Compatibility Tool commands.
help	Returns all help options for the Upgrade Compatibility Tool.

 

upgrade:check

The upgrade:check is the main command of the Adobe Commerce upgrade compatibility tool. It checks the core code for all custom changes and lists down the issues. For example:

Here, the <dir> refers to the Adobe Commerce directory path.

Available options:

• –current-version: The current Adobe Commerce version. (Mandatory)
• –min-issue-level: Filter issues according to their issue level.
• –ignore-current-version-compatibility-issues (or -i): Ignore issues from the current Adobe Commerce version.
• –coming-version (or -c): Specify the target Adobe Commerce version. (Default is the latest version)

 

dbschema:diff

The dbschema:diff checks for database schema differences between two Magento versions. It can be executed as:

The <current-version> and <target-version> argument refers to the versions of respective Adobe Commerce versions.

 

core:code:changes

This command lets you find the modifications in the core code of Adobe Commerce as compared to its vanilla version. The command can be executed as follows.

where <dir> and <vanilla dir> are arguments for the directories of current Adobe Commerce and its vanilla version.

 

refactor

The refactor command in the Adobe Commerce Upgrade Compatibility Tool allows fixing reduced set of issues:

• Deprecated functions that were previously allowed to be used without an argument.
• $this in Magento templates.
• PHP keyword final in private methods.

You can use the command as follows:

where the <dir> argument defines the directory of Adobe Commerce.

 

graphql:compare

This Magento Upgrade Compatibility Tool command is used to introspect and compare graphql endpoints and schemas of the installed Adobe Commerce version with the vanilla version.

Here, the arguments followed by the command define the directory of the Endpoint URL of existing & vanilla installations.

 

Further, you can also use the list command to get a list of the Upgrade Compatibility Tool commands and get help by using the help command.

 

Getting Ready for Magento Upgrade

Running Magento Upgrade Compatibility Tool before upgrading to the latest version can help save a lot of time and money by fixing potential incompatibility issues. The command line tool is easy-to-install and use for Adobe Commerce users. Unfortunately, it does not support the Magento open-source version! Merchants using the open-source version of Magento may face unexpected issues after upgrading to the latest Magento version.

Therefore, it is essential to take a complete backup of your Magento 2 store before proceeding with the upgrade, which can be helpful in case of critical issues. Our Magento professionals also advise testing all the third-party extensions and customizations in Magento 2 after the upgrade. Take help from an Adobe-certified Magento professional to upgrade your store to the latest version and mitigate the risks. 🚀