How to use data migration tool
My last post was about how to install and configure Magento 2 data migration tool. Now it is time to use it and to import data from your old shop. This post shows you a detailed introduction on how to set up data migration tool and use it. I also give you solutions for a number of problems you might get.
How to use data migration tool
There are 3 different things you can do with data migration tool:
- migrate configuration data1php bin/magento migrate:settings /path/to/config.xml
With this command you migrate only configuration data from core_config_data database table. That is all you can find in system->configuration in your Magento 1 adminhtml.
- migrate data (products, customers, oders, …)1php bin/magento migrate:data /path/to/config.xml
This command is the main procedure of this data migration tool. It migrates all data (products, customers, orders, …) to your now Magento 2 and uses configurations done with mapping files.
- import deltas1php bin/magento migrate:delta /path/to/config.xml
The main benefig of this tool is to import deltas, which means only changed data since last import. With this it is possible to create a Magento 2 shop parallel to your Magento 1 shop with same data basis. This minimize downtime if you switch to Magento 2.
The first step is now to copy configuration data.
My first try ended with an error message: Migration\Execution Invalid map file. I have not configured correct database connections and expected an error, but a different occured…
This message is a bit confusing. After some research, problem was that I deleted some files in config.xml from options tag. After copying from config.xml.dist I get the following more usable error: Access denied for user – one error message for each configured step in config.xml
Now configuration looks correct, so I set up correct connection data. The next run shows you the first error that has to do with data. If you have custom fields (not Magento default), then a message appears that you need to create mappings for this. It says: Source fields are not mapped.
If you do not want to do this, you can use param -a to ignore this differences and proceed. That may leads to another error.
Things become difficult now, because this is an SQL issue. You need to fix this in your database. The fix depends on type of error. An “Integrity constraint violation: 1062 Duplicate entry for key ‘STORE_GROUP_CODE’” can be easily fixed. Just make sure, that there are not 2 stores defined in core_store_group with the same name in your Magento 1 database.
Now it is time to migrate all other data including products, orders and customers. On my first run I got errors so I need to adapt configuration in detail. Before this is possible, a deeper understanding of this process is necessary.
Magento 2 Documentation lists 4 steps that are done:
- Integrity check
Each step has to check that the structure of data source (Magento 1 by default) and the structure of data destination (Magento 2) are compatible. If not – an error will be shown with entities that are not compatible. In case when fields have different datatypes (e.g. the same field has decimal datatype in Magento 1 and integer in Magento 2), a warning message will be shown (except when it was covered in Map file).
- Data Transfer
In case integrity check passed, transferring data is running. If some error appears then rollback will run to revert to previous state of Magento 2. If a step class implements RollbackInterface then “rollback” method will be executed in case of error.
- Volume check
After data has been migrated Volume Check provides additional check that all data was transferred correctly.
- Delta delivery
Delta functionality is responsible for delivering the rest of data that was added after main migration.
At the end of computing your migration, you will get a red error box that tells you when this error occurred. If not, there is a good chance, that migration was successful.
If you work with data migration tool to get your Magento 1 data to Magento 2, you may have to handle a bunch of different errors first. It is not possible to list you all errors and possible solutions, but with an example I want to give you a starting point.
My first data migration run stopped with the following volume check failed error:
This happens in step 3 volume check and is a validation of already imported data. The log shows you, that the data migration tool does a rollback. A red list of error message shows all attributes that caused that problem. So what to do?
The answer is quite easy. All this attributes need a backend model, that is not present in Magento 2. You need a special mapping for this and this is done in class-map.xml. For each attribute you need to declare a new mapping. If you have no class already, yo can leave to tag empty. This is an example for the first attribute:
After declaring all renames, the migration runs to the next problem. This time there is a problem with database configuration:
Warning: Error while sending QUERY packet. PID=4828 in vendor/magento/data-migration-tool/src/Migration/ResourceModel/Adapter/Mysql.php on line 169
This time we had to change max_allowed_packet param from you MySQL settings to more memory.
The data migration tool allows you to revert your recent migration if something brakes you database. Your first task after each try is to check, if frontend is accessible and if you can log into you adminhtml. If you get an error, you need to revert your changes, your database has an inconsistent status. Reverting is quite easy, simply use -r param like this:
Reverting is often usable, but sometimes it also crashes. If so, you need to import your last database backup.
Magento data migration tool is a very useful tool to migrate your shops data to the next level. It is quite cool to use, but it also has some problems. If you want to use it, be sure to invest some time to learn how it works, get an understanding of its steps and be prepared to solve some really strange problems.
I showed you how to solve two problems. Sometimes you need to do advanced configuration, sometimes you may also need to adapt database configuration.