Configure migration in a separate module

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

  1. Create a Magento 2 module.

    • <your Magento 2 install dir>/app/code/Vendor/Migration/composer.json
    {
        "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
    <?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
    <?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:

    cd <your Magento 2 install dir>
    
    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.

To configure the Data Migration Tool for migration:

  1. Log in to your application server as, or switch to, the 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. At a minimum, the config.xml file must contain access details to M1 and M2 databases and encryption keys.

    <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 must contain a value. You can find it inside the <key> 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:

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

<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 are working with the map.xml.dist file most of the time, the following table discusses each mapping and other files.

Mapping file nameDescription
class-map.xml.distDictionary of class mappings between Magento 1 and Magento 2
config.xml.distMain configuration file that specifies the Magento 1 and Magento 2 database configurations, step configuration, and links to mapping files
Adobe Commerce only. customer-attr-document-groups.xml.distList of tables used in the custom customer attributes step.
Adobe Commerce only. customer-attr-map.xml.distMap file that is used in Custom Customer Attributes Step.
deltalog.xml.distContains the list of tables required for database routines setup.
eav-attribute-groups.xml.distContains list of attributes that are used in Eav Step.
eav-document-groups.xml.distContains list of tables that are used in Eav Step.
log-document-groups.xml.distContains list of tables that are used in Log Step.
map-eav.xml.distMap file that is used in EAV Step.
map-log.xml.distLog-mapping file.
Adobe Commerce only. map-sales.xml.distMap file that is used in SalesOrder Step.
map.xml.distMapping file required for the map step.
settings.xml.distSetting migration configuration file that specifies rules required for migrating the core_config_data table.
customer-attribute-groups.xml.distContains list of attributes that are used in Customer Attributes Step.
customer-document-groups.xml.distContains list of tables that are used in Customer Attributes Step.
map-customer.xml.distMap file that is used in Customer Attributes Step.
order-grids-document-groups.xml.distContains list of tables that are used in OrderGrids Step.
map-document-groups.xml.distDefines what fields are updated when duplications occur on data insert
map-stores.xml.distMap file that is used in Stores Step.
map-tier-price.xml.distMap file that is used in Tier Price Step.
Adobe Commerce only. visual_merchandiser_map.xml.distMap file that is used in VisualMerchandiser Step.
Adobe Commerce only. visual_merchandiser_attribute_groups.xml.distContains list of attributes that are used in VisualMerchandiser Step.
Adobe Commerce only. visual_merchandiser_document_groups.xml.distContains list of tables that are used in VisualMerchandiser Step.

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

Commerce