ÃÛ¶¹ÊÓƵ

DocumentationCommerceUpgrade Guide

Complete upgrade prerequisites

Last update: Tue Dec 10 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Admin
  • Developer

It is important to understand what is necessary to run ÃÛ¶¹ÊÓƵ Commerce. You must first review the system requirements for the version you are planning to upgrade to.

After reviewing system requirements, you must complete the following prerequisites before upgrading your system:

  • Update all software
  • Verify that a supported search engine is installed
  • Convert database table format
  • Set the open files limit
  • Verify that cron jobs are running
  • Set DATA_CONVERTER_BATCH_SIZE
  • Verify file system permissions
  • Set the pub/ directory root
  • Install the Composer update plugin

Update all software

The system requirements describe exactly which versions of third-party software have been tested with ÃÛ¶¹ÊÓƵ Commerce releases.

Ensure that you updated all system requirements and dependencies in your environment. See PHP , PHP , PHP , and required PHP settings.

NOTE
For ÃÛ¶¹ÊÓƵ Commerce on cloud infrastructure Pro projects, you must create a Support ticket to install or update services in Staging and Production environments. Indicate the service changes needed and include your updated .magento.app.yaml and services.yaml files and PHP version in the ticket. It can take up to 48 hours for the Cloud infrastructure team to update your project. See Supported software and services.

Verify that a supported search engine is installed

ÃÛ¶¹ÊÓƵ Commerce requires Elasticsearch or OpenSearch to be installed in order to use the software.

If you are upgrading from 2.3.x to 2.4, you must check whether you are using MySQL, Elasticsearch, or a third-party extension as your catalog search engine in your 2.3.x instance. The result determines what you must do before upgrading to 2.4.

If you are upgrading patch releases within the 2.3.x or 2.4.x release lines, if Elasticsearch 7.x is already installed, you can optionally migrate to OpenSearch.

You can use the command line or the Admin to determine your catalog search engine:

  • Enter the bin/magento config:show catalog/search/engine command. The command returns a value of mysql, elasticsearch (which indicates Elasticsearch 2 is configured), elasticsearch5, elasticsearch6, elasticsearch7, or a custom value, indicating you have installed a third-party search engine. For versions earlier than 2.4.6, use the elasticsearch7 value for the Elasticsearch 7 or OpenSearch engine. For version 2.4.6 and later, use the opensearch value for the OpenSearch engine.

  • From the Admin, check the value of the Stores > Settings > Configuration > Catalog > Catalog > Catalog Search > Search Engine field.

The following sections describe what actions that you must take before upgrading to 2.4.0.

MySQL

As of 2.4, MySQL is no longer a supported catalog search engine. You must install and configure Elasticsearch or OpenSearch before upgrading. Use the following resources to help guide you through this process:

Some third-party catalog search engines run on top of the ÃÛ¶¹ÊÓƵ Commerce search engine. Contact your vendor to determine whether you must update your extension.

MariaDB

Reindexing on MariaDB 10.4 and 10.6 takes more time compared to previous MariaDB or MySQL versions. To speed up reindexing, we recommend setting these MariaDB configuration parameters:

If you experience performance degradation not related to indexation after upgrading to MariaDB 10.6, consider enabling the setting. For example, --query-cache-type=ON.

Before upgrading ÃÛ¶¹ÊÓƵ Commerce on cloud infrastructure projects, you may also need to upgrade MariaDB (see MariaDB upgrade best practices).

For example:

  • ÃÛ¶¹ÊÓƵ Commerce 2.4.6 with MariaDB version 10.5.1 or higher
  • ÃÛ¶¹ÊÓƵ Commerce 2.3.5 with MariaDB version 10.3 or earlier

In addition to these recommendations, you should consult with your database administrator on configuring the following parameters:

NOTE
These settings are available for on-premises deployments only. ÃÛ¶¹ÊÓƵ Commerce on cloud infrastructure customers do not have access to these settings.

Search engine

You must install and configure either Elasticsearch 7.6 or higher or OpenSearch 1.2 before upgrading to 2.4.0. ÃÛ¶¹ÊÓƵ no longer supports Elasticsearch 2.x, 5.x, and 6.x. Search engine configuration in the Configuration Guide describes the tasks you must perform after upgrading Elasticsearch to a supported version.

Refer to for full instructions on backing up your data, detecting potential migration issues, and testing upgrades before deploying to production. Depending on your current version of Elasticsearch, a full cluster restart may or may not be required.

Elasticsearch requires Java Development Kit (JDK) 1.8 or higher. See Install the Java Software Development Kit (JDK) to check which version of JDK is installed.

OpenSearch

OpenSearch is an open-source fork of Elasticsearch 7.10.2, following Elasticsearch’s licensing change. The following releases of ÃÛ¶¹ÊÓƵ Commerce introduces support for OpenSearch:

  • 2.4.6 (OpenSearch has a separate module and settings)
  • 2.4.5
  • 2.4.4
  • 2.4.3-p2
  • 2.3.7-p3

You can migrate from Elasticsearch to OpenSearch only if you are upgrading to a version of ÃÛ¶¹ÊÓƵ Commerce listed above (or higher).

OpenSearch requires JDK 1.8 or higher. See Install the Java Software Development Kit (JDK) to check which version of JDK is installed.

Search engine configuration describes the tasks you must perform after changing search engines.

Upgrade Elasticsearch

Support for Elasticsearch 8.x was introduced in ÃÛ¶¹ÊÓƵ Commerce 2.4.6. The following instructions show an example of upgrading Elasticsearch from 7.x to 8.x:

  1. Upgrade the Elasticsearch 7.x server to 8.x and make sure that is is up and running. See the .

  2. Enable the id_field_data field by adding the following configuration to your elasticsearch.yml file and restarting the Elasticsearch 8.x service.

    code language-yaml 
    indices:
  id_field_data:
    enabled: true
    note info
    INFO
    To support Elasticsearch 8.x, ÃÛ¶¹ÊÓƵ Commerce 2.4.6 disallows the indices.id_field_data property by default and uses the _id field in the docvalue_fields property.

  3. In the root directory of your ÃÛ¶¹ÊÓƵ Commerce project, update your Composer dependencies to remove the Magento_Elasticsearch7 module and install the Magento_Elasticsearch8 module.

    code language-bash 
    composer require magento/module-elasticsearch-8 --update-with-all-dependencies

  4. Update your project components.

    code language-bash 
    bin/magento setup:upgrade

  5. Configure Elasticsearch in the Admin.

  6. Reindex the catalog index.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  7. Delete all items from the enabled cache types.

    code language-bash 
    bin/magento cache:clean

Downgrade Elasticsearch

If you inadvertently upgrade the version of Elasticsearch on your server or determine that you need to downgrade for any other reason, you must also update your ÃÛ¶¹ÊÓƵ Commerce project dependencies. For example, to downgrade from Elasticsearch 8.x to 7.x

  1. Downgrade the Elasticsearch 8.x server to 7.x and make sure that is is up and running. See the .

  2. In the root directory of your ÃÛ¶¹ÊÓƵ Commerce project, update your Composer dependencies to remove the Magento_Elasticsearch8 module and its Composer dependencies and install the Magento_Elasticsearch7 module.

    code language-bash 
    composer remove magento/module-elasticsearch-8

  3. Update your project components.

    code language-bash 
    bin/magento setup:upgrade

  4. Configure Elasticsearch in the Admin.

  5. Reindex the catalog index.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  6. Delete all items from the enabled cache types.

    code language-bash 
    bin/magento cache:clean

Third-party extensions

We recommend that you contact your search engine vendor to determine whether your extension is fully compatible with an ÃÛ¶¹ÊÓƵ Commerce release.

Convert database table format

You must convert the format of all database tables from COMPACT to DYNAMIC. You must also convert the storage engine type from MyISAM to InnoDB. See best practices.

Set the open files limit

Setting the open files limit (ulimit) can help avoid failure from multiple recursive calls of long query strings or issues with using the bin/magento setup:rollback command. This command is different for different UNIX shells. Consult your individual flavor for specifics about the ulimit command.

ÃÛ¶¹ÊÓƵ recommends setting the open files to a value of 65536 or more, but you can use a larger value if necessary. You can set the ulimit on the command line or you can make it a permanent setting for the user’s shell.

To set the ulimit from the command line:

  1. Switch to the file system owner.

  2. Set the ulimit to 65536.

    code language-bash 
    ulimit -n 65536

To set the value in your Bash shell:

  1. Switch to the file system owner.

  2. Open /home/<username>/.bashrc in a text editor.

  3. Add the following line:

    code language-bash 
    ulimit -n 65536

  4. Save your changes to the .bashrc file and exit the text editor.

IMPORTANT
We recommend that you avoid setting a value for the pcre.recursion_limit property in the php.ini file because it can result in incomplete rollbacks with no failure notice.

Verify that cron jobs are running

The UNIX task scheduler cron is critical to day-to-day ÃÛ¶¹ÊÓƵ Commerce operations. It schedules things like reindexing, newsletters, e-mails, and sitemaps. Several features require at least one cron job running as the file system owner.

To verify that your cron job is set up properly, check the crontab by entering the following command as the file system owner:

NOTE
The crontab is the configuration file responsible for running cron jobs.
crontab -l

Results similar to the following should display:

#~ MAGENTO START c5f9e5ed71cceaabc4d4fd9b3e827a2b
* * * * * /usr/bin/php /var/www/html/magento2/bin/magento cron:run 2>&1 | grep -v "Ran jobs by schedule" >> /var/www/html/magento2/var/log/magento.cron.log
#~ MAGENTO END c5f9e5ed71cceaabc4d4fd9b3e827a2b

Another symptom of cron not running is the following error in the Admin:

System messages - cron not running

To see the error, click System Messages at the top of the window as follows:

System messages notification

See Configure and run cron for more information.

Set DATA_CONVERTER_BATCH_SIZE

ÃÛ¶¹ÊÓƵ Commerce 2.4 includes security enhancements that require some data to be converted from serialized to JSON. This conversion occurs during the upgrade and it can take a long time, depending on how much data is in your database.

The following tables are affected the most:

  • catalogrule
  • core_config_data
  • magento_reward_history
  • quote_payment
  • quote
  • sales_order_payment
  • sales_order
  • salesrule
  • url_rewrite

If you have a large amount of data, you can improve performance by setting the value of an environment variable, DATA_CONVERTER_BATCH_SIZE. By default, the value is set to 50,000.

To set the environment variable:

  1. Switch to the file system owner.

  2. Set the variable:

    code language-bash 
    export DATA_CONVERTER_BATCH_SIZE=100000
    note note
    NOTE
    DATA_CONVERTER_BATCH_SIZE requires memory; avoid setting it to a large value (approximately 1 GB) without testing it first.

  3. After your upgrade is complete, you can unset the variable:

    code language-bash 
    unset DATA_CONVERTER_BATCH_SIZE

Verify file system permissions

For security reasons, ÃÛ¶¹ÊÓƵ Commerce requires certain permissions on the file system. Permissions are different from ownership. Ownership determines who can perform actions on the file system; permissions determine what the user can do.

Directories in the file system must be writable by the file system owner’s group.

To verify that your file system permissions are set properly, either log into the application server or use your hosting provider’s file manager application.

For example, enter the following command if the application is installed in /var/www/html/magento2:

ls -l /var/www/html/magento2

Sample output:

total 1028
drwxrwx---. 12 magento_user apache   4096 Jun  7 07:55 .
drwxr-xr-x.  3 root         root     4096 May 11 14:29 ..
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 app
drwxrwx---.  2 magento_user apache   4096 Jun  7 07:53 bin
-rw-rw----.  1 magento_user apache 439792 Apr 27 21:23 CHANGELOG.md
-rw-rw----.  1 magento_user apache   3422 Apr 27 21:23 composer.json
-rw-rw----.  1 magento_user apache 425214 Apr 27 21:27 composer.lock
-rw-rw----.  1 magento_user apache   3425 Apr 27 21:23 CONTRIBUTING.md
-rw-rw----.  1 magento_user apache  10011 Apr 27 21:23 CONTRIBUTOR_LICENSE_AGREEMENT.html
-rw-rw----.  1 magento_user apache    631 Apr 27 21:23 COPYING.txt
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 dev
-rw-rw----.  1 magento_user apache   2926 Apr 27 21:23 Gruntfile.js
-rw-rw----.  1 magento_user apache   7592 Apr 27 21:23 .htaccess
-rw-rw----.  1 magento_user apache   6419 Apr 27 21:23 .htaccess.sample
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 lib
-rw-rw----.  1 magento_user apache  10376 Apr 27 21:23 LICENSE_AFL.txt
-rw-rw----.  1 magento_user apache  30634 Apr 27 21:23 LICENSE_EE.txt
-rw-rw----.  1 magento_user apache  10364 Apr 27 21:23 LICENSE.txt
-rw-rw----.  1 magento_user apache   4108 Apr 27 21:23 nginx.conf.sample
-rw-rw----.  1 magento_user apache   1427 Apr 27 21:23 package.json
-rw-rw----.  1 magento_user apache   1659 Apr 27 21:23 .php_cs
-rw-rw----.  1 magento_user apache    804 Apr 27 21:23 php.ini.sample
drwxrwx---.  2 magento_user apache   4096 Jun  7 07:53 phpserver
drwxrwx---.  6 magento_user apache   4096 Jun  7 07:53 pub
-rw-rw----.  1 magento_user apache   2207 Apr 27 21:23 README_EE.md
drwxrwx---.  7 magento_user apache   4096 Jun  7 07:53 setup
-rw-rw----.  1 magento_user apache   3731 Apr 27 21:23 .travis.yml
drwxrwx---.  7 magento_user apache   4096 Jun  7 07:53 update
drwxrws---. 11 magento_user apache   4096 Jun 13 16:05 var
drwxrws---. 29 magento_user apache   4096 Jun  7 07:53 vendor

See the following for an explanation of the sample output:

  • Most of the files are -rw-rw----, which is 660
  • drwxrwx--- = 770
  • -rw-rw-rw- = 666
  • The file system owner is magento_user

To get more detailed information, you can enter the following command:

ls -la /var/www/html/magento2/pub

Because ÃÛ¶¹ÊÓƵ Commerce deploys static file assets to subdirectories of pub, it’s a good idea to verify permissions and ownership there as well.

For more information, see File system permissions and ownership.

Set the pub/ directory root

See Modify docroot to improve security for more details.

Install the Composer update plugin

The Composer plugin resolves changes that must be made to the root project composer.json file before updating to a new product requirement.

The plugin partially automates the manual upgrade by identifying and helping you resolve dependency conflicts instead of requiring you to identify and fix them manually.

To install the plugin:

  1. Add the package to your composer.json file.

    code language-bash 
    composer require magento/composer-root-update-plugin ~2.0 --no-update

  2. Update the dependencies:

    code language-bash 
    composer update
recommendation-more-help
83a60e0e-8849-4685-a8cd-c129ecd795ea