Configure migration

Overview of Data Migration Tool configuration

After you install the data migration tool, the following directory contains mapping and configuration files:

• Magento Open Source:

  • <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/opensource-to-opensource: Configuration and scripts for migrating from Magento Open Source 1 to Magento Open Source 2

• Adobe Commerce:

  • <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/opensource-to-commerce: Configuration and scripts for migrating from Magento Open Source 1 to Adobe Commerce 2
  • <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/commerce-to-commerce: Configuration and scripts for migrating from Adobe Commerce 1 to Adobe Commerce 2

The preceding directories contain subdirectories for each supported version.

Configuring the migration

There are two ways to configure the Data Migration Tool:

• Configure the Data Migration Tool in a separate module (recommended)
• Change the Data Migration Tool configuration in the <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/ directory.

To use source control to manage your migration configuration and use it for deployment, you must create a separate module. If you plan to run the Data Migration Tool locally only, you can edit files in the <your Magento 2 install dir>/vendor/magento/data-migration-tool/ directory directly.

Configure migration in a separate module

Before you migrate any data, you must create a Magento 2 module.

1. Create a new Magento 2 module.

   • <your Magento 2 install dir>/app/code/Vendor/Migration/composer.json

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   {
       "name": "vendor/migration",
       "description": "Providing config for migration",
       "config": {
           "sort-packages": true
       },
       "require": {
           "magento/framework": "*",
           "magento/data-migration-tool": "*"
       },
       "type": "magento2-module",
       "autoload": {
           "files": [
               "registration.php"
           ],
           "psr-4": {
               "Vendor\\Migration\\": ""
           }
       },
       "version": "1.0.0"
   }
   

   • <your Magento 2 install dir>/app/code/Vendor/Migration/registration.php

   1
   2
   3
   4
   5
   6
   7
   <?php
   
   \Magento\Framework\Component\ComponentRegistrar::register(
       \Magento\Framework\Component\ComponentRegistrar::MODULE,
       'Vendor_Migration',
       __DIR__
   );
   

   • <your Magento 2 install dir>/app/code/Vendor/Migration/etc/module.xml

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   <?xml version="1.0"?>
   
   <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
       <module name="Vendor_Migration" setup_version="1.0.0">
           <sequence>
               <module name="Magento_DataMigrationTool"/>
           </sequence>
       </module>
   </config>
   

2. Copy the config.xml.dist configuration file from the appropriate directory of the Data Migration Tool (<your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/<migration edition>/<ce or version>) into the <your Magento 2 install dir>/app/code/Vendor/Migration/etc/<migration edition>/<ce or version>/config.xml file.

   For example, if you migrate Magento 1.9.3.6 Community Edition to Magento 2 Open Source:

   1
   cd <your Magento 2 install dir>
   

   1
   cp vendor/magento/data-migration-tool/etc/opensource-to-opensource/1.9.3.6/config.xml.dist app/code/Vendor/Migration/etc/opensource-to-opensource/1.9.3.6/config.xml
   

3. In the config.xml file, you must set access details to M1 and M2 databases and encryption key.

4. If your M1 store has custom changes, you should map the rest of your configuration files to your Magento 1 store customizations. See Work with configuration and mapping files.

Configure migration in vendor folder

Before you migrate any data, you must create a config.xml configuration file from the provided sample.

There are two possible ways to configure the Data Migration Tool for migration:

1. Log in to your Magento server as, or switch to, the file system owner.

2. Change to the following directory:

   1
   <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/<migration edition>/<ce or version>
   

3. Enter the following command to create a config.xml from the provided sample:

   1
   cp config.xml.dist config.xml
   

4. Open config.xml in a text editor.

5. At a minimum, the config.xml file must contain access details to M1 and M2 databases and encryption keys.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   <source>
      <database host="127.0.0.1" name="magento1" user="root"/>
   </source>
   <destination>
      <database host="127.0.0.1" name="magento2" user="root"/>
   </destination>
   <options>
      <crypt_key />
   </options>
   

   The tag must contain a value. You can find it inside the tag, which is located in the app/etc/local.xml file on your Magento 1 instance.

   Optional parameters:

   • Database user password: password=<password>
   • Database custom port: port=<port>
   • Table prefix: <source_prefix>, <dest_prefix>

   For example, if your database owner’s username is root with password pass and you use the prefix magento1 in your Magento 1 database, use the following in config.xml:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   <source>
      <database host="127.0.0.1" name="magento1" user="root" password="pass"/>
   </source>
   <destination>
      <database host="127.0.0.1" name="magento2" user="root" password="pass"/>
   </destination>
   <options>
      <source_prefix>magento1</source_prefix>
      <crypt_key>f3e25abe619dae2387df9fs594f01985</crypt_key>
   </options>
   

When finished, save your changes to config.xml and exit the text editor.

Connect using the TLS protocol

You can also connect to a database using the TLS protocol (i.e., using public/private cryptographic keys). Add the following optional attributes to the database element:

• ssl_ca
• ssl_cert
• ssl_key

For example:

1
2
3
4
5
6
<source>
    <database host="localhost" name="magento1" user="root" ssl_ca="/path/to/file" ssl_cert="/path/to/file" ssl_key="/path/to/file"/>
</source>
<destination>
    <database host="localhost" name="magento2" user="root" ssl_ca="/path/to/file" ssl_cert="/path/to/file" ssl_key="/path/to/file"/>
</destination>

Work with configuration and mapping files

The Data Migration Tool uses mapping files to enable you to perform custom database mapping between your Magento 1 and Magento 2 databases, including:

• Changing table names

• Changing field names

• Ignoring tables or fields

• Adapt transferring data of a field to Magento 2 format

Mapping files for supported Magento versions are located in subdirectories of <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc

To use the mapping files:

1. Copy them from <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/<migration edition>/<ce or version>/ to <your Magento 2 install dir>/app/code/Vendor/Migration/etc/<migration edition>/<ce or version>/ and remove the .dist extension.

2. Update the path to the newly copied file in the <options> node of config.xml. The updated path should be one of the following:

   1. Absolute file path, e. g. /var/www/html/app/code/Vendor/Migration/etc/opensource-to-opensource/1.9.4.1/map.xml
   2. magento/data-migration-tool module relative file path: etc/opensource-to-opensource/1.9.4.1/map.xml
   3. Magento root-relative file path: app/code/Vendor/Migration/etc/opensource-to-opensource/1.9.4.1/map.xml

The <Magento 2 dir>/vendor/magento/data-migration-tool/etc and <Magento 2 dir>/vendor/magento/data-migration-tool/etc/<ce version> directories contain the following configuration files:

Even though you will be working with map.xml.dist file most of the time, the following table discusses each mapping and other files.

You can refer to Data Migration Tool Technical Specification for more details.

Related topics

Migrate using data migration tool