Magento 2.1.18 is the final 2.1.x release. After June 2019, Magento 2.1.x will no longer receive security patches, quality fixes, or documentation updates.
To maintain your site's performance, security, and PCI compliance, upgrade to the latest version of Magento.

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/ce-to-ce: Configuration and scripts for migrating from Magento Open Source 1 to Magento Open Source 2
  • Magento Commerce:

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

The preceding directories contain subdirectories for each supported version.

Configuring the migration

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

To create a configuration file:

  1. Log in to your Magento server as, or switch to, the Magento 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. Specify the following at minimum:

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 <crypt_key> tag is mandatory to fill. It can be found in local.xml file which is located in the directory of Magento 1 instance at app/etc/local.xml in <key> tag

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.

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. Rename or copy them to remove the .dist extension.

  2. Edit them using the schema located in

    <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc.

  3. Then change config.xml in <options> node with the new name of the file.

The <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc and <your Magento 2 install 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.

Mapping file name Description
class-map.xml.dist Dictionary of class mappings between Magento 1 and Magento 2
config.xml.dist Main configuration file that specifies the Magento 1 and Magento 2 database configurations, step configuration, and links to mapping files
Magento Commerce only. customer-attr-document-groups.xml.dist List of tables used in the custom customer attributes step.
Magento Commerce only. customer-attr-map.xml.dist Map file that is used in Custom Customer Attributes Step.
deltalog.xml.dist Contains the list of tables required for database routines setup.
eav-attribute-groups.xml.dist Contains list of attributes that are used in Eav Step.
eav-document-groups.xml.dist Contains list of tables that are used in Eav Step.
log-document-groups.xml.dist Contains list of tables that are used in Log Step.
map-eav.xml.dist Map file that is used in EAV Step.
map-log.xml.dist Log mapping file.
Magento Commerce only. map-sales.xml.dist Map file that is used in SalesOrder step.
map.xml.dist Mapping file required for the map step.
settings.xml.dist Setting migration configuration file that specifies rules required for migrating the core_config_data table.
customer-attribute-groups.xml Contains list of attributes that are used in Customer Attributes Step.
customer-document-groups.xml Contains list of tables that are used in Customer Attributes Step.
map-customer.xml Map file that is used in Customer Attributes Step.
order-grids-document-groups.xml Contains list of tables that are used in OrderGrids Step.

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

Next step

Migrate using data migration tool

Updated