Configure migration in a separate module
Before you migrate any data, you must create a Magento 2 module.
-
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>
-
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
toMagento 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
-
In the
config.xml
file, you must set access details to M1 and M2 databases and encryption key. -
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:
-
Log in to your application server as, or switch to, the file system owner.
-
Change to the following directory:
<your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/<migration edition>/<ce or version>
-
Enter the following command to create a
config.xml
from the provided sample:cp config.xml.dist config.xml
-
Open
config.xml
in a text editor. -
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 passwordpass
and you use the prefixmagento1
in your Magento 1 database, use the following inconfig.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>
- Database user password:
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:
-
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. -
Update the path to the newly copied file in the
<options>
node ofconfig.xml
. The updated path should be one of the following:- Absolute file path, e. g.
/var/www/html/app/code/Vendor/Migration/etc/opensource-to-opensource/1.9.4.1/map.xml
- magento/data-migration-tool module relative file path:
etc/opensource-to-opensource/1.9.4.1/map.xml
- Magento root-relative file path:
app/code/Vendor/Migration/etc/opensource-to-opensource/1.9.4.1/map.xml
- Absolute file path, e. g.
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 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 |
Adobe Commerce only. customer-attr-document-groups.xml.dist | List of tables used in the custom customer attributes step. |
Adobe 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. |
Adobe 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.dist | Contains list of attributes that are used in Customer Attributes Step. |
customer-document-groups.xml.dist | Contains list of tables that are used in Customer Attributes Step. |
map-customer.xml.dist | Map file that is used in Customer Attributes Step. |
order-grids-document-groups.xml.dist | Contains list of tables that are used in OrderGrids Step. |
map-document-groups.xml.dist | Defines what fields are updated when duplications occur on data insert |
map-stores.xml.dist | Map file that is used in Stores Step. |
map-tier-price.xml.dist | Map file that is used in Tier Price Step. |
Adobe Commerce only. visual_merchandiser_map.xml.dist | Map file that is used in VisualMerchandiser Step. |
Adobe Commerce only. visual_merchandiser_attribute_groups.xml.dist | Contains list of attributes that are used in VisualMerchandiser Step. |
Adobe Commerce only. visual_merchandiser_document_groups.xml.dist | Contains list of tables that are used in VisualMerchandiser Step. |
You can refer to Data Migration Tool Technical Specification for more details.