Testing Magento 2 Data Migration Tool

As you are probably aware of, Magento 2 will come with a brand new architecture and database design. To ease up upgrade process, Magento released official Data Migration Tool that will help developers migrate store data from Magento 1 to Magento 2.

Official resources:

• Whitepaper
• Migration Guide
• Migration Tool on Github

Data Migration Tool transfers data from M1 database to M2 database based on set of rules defined in xml files. To be clear, this tool only transfers data. Themes and customizations of your store can’t be automatically changed or migrated to Magento2.

You install tool into empty Magento2 installation with Composer. It’s not an extension, but standalone shell app that requires Magento2 framework to work. It’s located in vendor/magento/data-migration-tool/bin/migrate.

You set it up by editing configuration xml files in vendor/magento/data-migration-tool/etc/ce-to-ce/ folder. On supported default Magento installations, minimum required would be to configure source(M1) and destination(M2) database connections in config.xml:

<source>
<database host="localhost" name="magento1_db" user="root"/>
</source>
<destination>
<database host="localhost" name="magento2_db" user="root"/>
</destination>

config.xml is main configuration file, it defines connection, which steps to execute, path to other specific xmls. map.xml holds main global mapping definitions, which tables or columns to ignore, what is renamed to what, while other xml files are step-specific things.

There are 3 main commands/steps for the migration: settings, data and delta. This and their sub-steps can be seen in config.xml.

cd vendor/magento/data-migration-tool/bin/
php migrate --help
 
Usage:
migrate <mode> --config=path/to/config.xml [options]
migrate --help
 
Possible modes:
settings Migrate system configuration
data Main migration of data
delta Migrate the data is added into Magento after the main migration
 
Available options:
--reset Reset the current position of migration to start from the beginning
--config <value> Path to main configuration file, i.e.: etc/m1_version/config.xml
--verbose <level> Verbosity levels: DEBUG, INFO, ERROR
--help Help information

Migrate Settings

First, you migrate settings, websites and stores to M2. Most of Magento data is related to websites and stores, so this needs to go first.

Migrate Data

Data migration will transfer categories, products, customers, orders, wishlists, ratings, everything you can think of into M2. I believe we’ll even turn off some things, like logs or quotes.

Migrate Delta

Now this is where it gets interesting. After successful data migration, you can always just append new M1 entries to M2 database with delta migration, it will continue where it stopped last time. Delta doesn’t migrate new or changed products or categories (at the moment of writing), only customers, orders, and similar customer related data.

While doing data migration, set of m2_* tables are created in your M1 database with set of triggers that enables tracking changes.

Delta is here to reduce migration time to minimum when going live with M2.

Migrate Media

Media files can simply be copy/pasted to appropriate places in M2 after products and categories are migrated, simple as that.

Customize Migration

Since there is no such thing as default Magento in the real world (XD), developers will always need to configure or customize this tool. The tool itself is flexible, since most of mapping is defined through xml files and filtered through php classes, Magento team really did good job here.

Let’s say we have custom varchar sales_flat_order.custom_column in M1. If we run data migration, we’ll end up with an error:

[ERROR]: Source fields not mapped. Document: sales_flat_order. Fields: custom_column

To ignore it we need to add following to map.xml file.

<source>
<field_rules>
<ignore>
<field>sales_flat_order.custom_column</field>
</ignore>
..

The only remark I have is that maybe unknown columns should be ignored by default. If there is column in M1 that isn’t defined in xml, the tool should ignore it, it would save lot of time.

Let’s say we want to move values to renamed custom_column and modify values in the process:

<source>
<field_rules>
..
<transform>
<field>sales_flat_order.custom_column</field>
<handler class="MigrationHandlerAddPrefix">
<param name="prefix" value="inchoo_"/>
</handler>
</transform>
<move>
<field>sales_flat_order.custom_column</field>
<to>sales_order.new_custom_column</to>
</move>
..

Example shows that Handler class can be used, or custom one created, for changing values on the fly during migration.

If mapping isn’t enough, whole new custom step can be created. Each step is composed out of Integrity, Data and Volume classes. Integrity is triggered before migration to check if everything is ok with mapping, Data transfers data, Volume checks if everything is ok after migration. Delta class can be added to support delta migrations.

Conclusion

Migration tool is great starting point in M1 to M2 migration, developers can customize it and it will really save tons of work. It’s also fast, since it’s direct database to database migration.

At the moment of writing, only 1.9.1.0 was supported, but I successfully migrated default 1.9.2.0 with sample data and additional tables without many problems. Other M1 versions will be supported when M2 comes out.

So, most likely data migration scenario is.. You setup empty M2 and migrate data from your M1 site. You check, setup and develop everything needed for your new M2 store. When you’re done and ready to switch to M2, migrate delta, go live.

Now, we know how confusing all of this can be. But, we’re here to help you with the process of Magento 2 Upgrade. Feel free to drop us a line