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
  • Magento 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 Magento Commerce 2
    • <your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/commerce-to-commerce: 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:

    <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:

    cp config.xml.dist config.xml
  4. Open config.xml in a text editor.

  5. Specify the following at minimum:

    <database host="" name="magento1" user="root"/>
    <database host="" name="magento2" user="root"/>
    <crypt_key />

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:

    <database host="" name="magento1" user="root" password="pass"/>
    <database host="" name="magento2" user="root" password="pass"/>

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:

    <database host="localhost" name="magento1" user="root" ssl_ca="/path/to/file" ssl_cert="/path/to/file" ssl_key="/path/to/file"/>
    <database host="localhost" name="magento2" user="root" ssl_ca="/path/to/file" ssl_cert="/path/to/file" ssl_key="/path/to/file"/>

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