Complete upgrade prerequisites
It is important to understand what is necessary to run Adobe 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 Adobe Commerce releases.
Ensure that you updated all system requirements and dependencies in your environment. See PHP 7.4, PHP 8.0, PHP 8.1, and required PHP settings.
.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
Adobe 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 ofmysql
,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 theelasticsearch7
value for the Elasticsearch 7 or OpenSearch engine. For version 2.4.6 and later, use theopensearch
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:
- Install and configure Elasticsearch
- Installing Elasticsearch
- Configure nginx or Apache to work with your search engine
- Configure Commerce to use Elasticsearch and reindex
Some third-party catalog search engines run on top of the Adobe 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 --query-cache-type
setting. For example, --query-cache-type=ON
.
Before upgrading Adobe Commerce on cloud infrastructure projects, you may also need to upgrade MariaDB (see MariaDB upgrade best practices).
For example:
- Adobe Commerce 2.4.6 with MariaDB version 10.5.1 or higher
- Adobe 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:
Search engine
You must install and configure either Elasticsearch 7.6 or higher or OpenSearch 1.2 before upgrading to 2.4.0. Adobe 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 Upgrading Elasticsearch 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 Adobe 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 Adobe 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 Adobe Commerce 2.4.6. The following instructions show an example of upgrading Elasticsearch from 7.x to 8.x:
-
Upgrade the Elasticsearch 7.x server to 8.x and make sure that is is up and running. See the Elasticsearch documentation.
-
Enable the
id_field_data
field by adding the following configuration to yourelasticsearch.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, Adobe Commerce 2.4.6 disallows the indices.id_field_data
property by default and uses the_id
field in thedocvalue_fields
property. -
In the root directory of your Adobe Commerce project, update your Composer dependencies to remove the
Magento_Elasticsearch7
module and install theMagento_Elasticsearch8
module.code language-bash composer require magento/module-elasticsearch-8 --update-with-all-dependencies
-
Update your project components.
code language-bash bin/magento setup:upgrade
-
Configure Elasticsearch in the Admin.
-
Reindex the catalog index.
code language-bash bin/magento indexer:reindex catalogsearch_fulltext
-
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 Adobe Commerce project dependencies. For example, to downgrade from Elasticsearch 8.x to 7.x
-
Downgrade the Elasticsearch 8.x server to 7.x and make sure that is is up and running. See the Elasticsearch documentation.
-
In the root directory of your Adobe Commerce project, update your Composer dependencies to remove the
Magento_Elasticsearch8
module and its Composer dependencies and install theMagento_Elasticsearch7
module.code language-bash composer remove magento/module-elasticsearch-8
-
Update your project components.
code language-bash bin/magento setup:upgrade
-
Configure Elasticsearch in the Admin.
-
Reindex the catalog index.
code language-bash bin/magento indexer:reindex catalogsearch_fulltext
-
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 Adobe 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.
Adobe recommends setting the open files ulimit 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:
-
Switch to the file system owner.
-
Set the ulimit to
65536
.code language-bash ulimit -n 65536
To set the value in your Bash shell:
-
Switch to the file system owner.
-
Open
/home/<username>/.bashrc
in a text editor. -
Add the following line:
code language-bash ulimit -n 65536
-
Save your changes to the
.bashrc
file and exit the text editor.
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 Adobe 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:
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:
To see the error, click System Messages at the top of the window as follows:
See Configure and run cron for more information.
Set DATA_CONVERTER_BATCH_SIZE
Adobe 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:
-
Switch to the file system owner.
-
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. -
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, Adobe 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 is660
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 Adobe 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 magento/composer-root-update-plugin
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:
-
Add the package to your
composer.json
file.code language-bash composer require magento/composer-root-update-plugin ~2.0 --no-update
-
Update the dependencies:
code language-bash composer update