Magento Series: Writing Migration Scripts

Magento uses schema/data migrations to provide data persistence and database updates. These migrations contain instructions for creating the required tables and filling them during the initial installation, transforming the database scheme and information for each possible application version.

How to process database updates?

There are two ways to process database updates

• Declarative schema
• Migration setup/migration scripts.

Today, the declarative schema has replaced the migration setup approach, but either one depends on the project at hand. 

What is the declarative schema?

Magento 2.3 introduced a new declarative approach which resolves many of the previous limitations. Most importantly, it resolves the need for updating the install scripts based on versions and the mess that comes with reverting and re-executing the scripts.

The declarative schema allows the developers to decide the final states of a particular database. Then the system adjusts to those changes automatically, thus saving the developers from performing many redundant functions. Unlike the upgrade scripts, it helps developers not to write various scripts for each new module version.

Magento provides several commands to help convert your installation and upgrade scripts to a declarative schema. These commands also allow you to test your changes, roll back your changes if anything goes wrong, and help your module maintain backward compatibility.

Magento prioritizes the declarative schema approach and executes updates from the db_schema.xml before the data and schema patches.

Magento 2.3 introduced data patches, a new way for modules to apply data changes.

What is the migration setup?

Until Magento 2.3, the migration setup, also called migration scripts, was the primary and suggested way to process database updates, for example, creating tables, modifying fields, renaming, or changing constraints. Developers had to write PHP database scripts for each new Magento version. Various scripts were required for

• Installing and upgrading the database schema
• Installing and upgrading data
• Invoking other operations that are required each time after installing or upgrading Magento.

When a customer upgrades Magento to a version several releases ahead of the installed version, the upgrade script for each intermediate release still executes. Developers were required to understand what each install and upgrade script contained fully.

Which database update type should I use?

Going forward, you should work towards using the declarative schema approach. However, for older Magento versions, this is not an option. So if you have to support older versions, then the old install schema approach is the safer bet.

Another important factor here is backward incompatibility. Once you convert a module to the declarative schema approach, it cannot be reverted to upgrade scripts. If you wish to support older versions of Magento, you will still need to use the install schema approach.

Was this article helpful? For more Magento (Adobe Commerce) insights from our certified developers, browse the Magento category in scandiweb blog. If you need assistance, contact our team directly!

Related articles:

Magento 2 Version Upgrade Process Breakdown

Advice from Analytics team: 3rd party scripts migration for PWA projects

Share on: