Develop data and schema patches

A data patch is a class that contains data modification instructions. It is defined in a <Vendor>/<Module_Name>/Setup/Patch/Data/<Patch_Name>.php file and implements \Magento\Framework\Setup\Patch\DataPatchInterface.

A schema patch contains custom schema modification instructions. These modifications can be complex. It is defined in a <Vendor>/<Module_Name>/Setup/Patch/Schema/<Patch_Name>.php file and implements \Magento\Framework\Setup\Patch\SchemaPatchInterface.

Unlike the declarative schema approach, patches will only be applied once. A list of applied patches is stored in the patch_list database table. An unapplied patch will be applied when running the setup:upgrade from the Magento CLI.

Optionally, if you plan to enable rollback for your patch during module uninstallation, then you must implement \Magento\Framework\Setup\Patch\PatchRevertableInterface.

The declarative schema approach removes the version from the setup_module table (in a backward compatible way), leaving only the Composer version. Therefore, you can create all new patches and modules without specifying a setup_module version.

The sequence of installing patches is handled through a dependency-based approach. Patches can either be independent or dependent on other patches. Independent patches can be installed in any sequence. A dependent patch requires a minimal number of patches so that it can be installed successfully.

To define a dependency in a patch, add the method public static function getDependencies() to the patch class and return the class names of the patches this patch depends on. The dependency can be in any module.

public static function getDependencies()
{
    return [
        \SomeVendor\SomeModule\Setup\Patch\Data\SomePatch::class
    ];
}
CopyCopied to your clipboard
1public static function getDependencies()
2{
3    return [
4        \SomeVendor\SomeModule\Setup\Patch\Data\SomePatch::class
5    ];
6}

The following code sample defines a data patch class that has a dependency.

<?php
/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */

namespace Magento\DummyModule\Setup\Patch\Data;

use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Framework\Setup\Patch\DataPatchInterface;
use Magento\Framework\Setup\Patch\PatchRevertableInterface;

class DummyPatch
    implements DataPatchInterface,
    PatchRevertableInterface
{
    /**
     * @var ModuleDataSetupInterface
     */
    private $moduleDataSetup;

    /**
     * @param ModuleDataSetupInterface $moduleDataSetup
     */
    public function __construct(
        ModuleDataSetupInterface $moduleDataSetup
    ) {
        /**
         * If before, we pass $setup as argument in install/upgrade function, from now we start
         * inject it with DI. If you want to use setup, you can inject it, with the same way as here
         */
        $this->moduleDataSetup = $moduleDataSetup;
    }

    /**
     * @inheritdoc
     */
    public function apply()
    {
        $this->moduleDataSetup->getConnection()->startSetup();
        //The code that you want apply in the patch
        //Please note, that one patch is responsible only for one setup version
        //So one UpgradeData can consist of few data patches
        $this->moduleDataSetup->getConnection()->endSetup();
    }

    /**
     * @inheritdoc
     */
    public static function getDependencies()
    {
        /**
         * This is dependency to another patch. Dependency should be applied first
         * One patch can have few dependencies
         * Patches do not have versions, so if in old approach with Install/Ugrade data scripts you used
         * versions, right now you need to point from patch with higher version to patch with lower version
         * But please, note, that some of your patches can be independent and can be installed in any sequence
         * So use dependencies only if this important for you
         */
        return [
            SomeDependency::class
        ];
    }

    public function revert()
    {
        $this->moduleDataSetup->getConnection()->startSetup();
        //Here should go code that will revert all operations from `apply` method
        //Please note, that some operations, like removing data from column, that is in role of foreign key reference
        //is dangerous, because it can trigger ON DELETE statement
        $this->moduleDataSetup->getConnection()->endSetup();
    }

    /**
     * @inheritdoc
     */
    public function getAliases()
    {
        /**
         * This internal method, that means that some patches with time can change their names,
         * but changing name should not affect installation process, that's why if we will change name of the patch
         * we will add alias here
         */
        return [];
    }
}
CopyCopied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace Magento\DummyModule\Setup\Patch\Data;
8
9use Magento\Framework\Setup\ModuleDataSetupInterface;
10use Magento\Framework\Setup\Patch\DataPatchInterface;
11use Magento\Framework\Setup\Patch\PatchRevertableInterface;
12
13class DummyPatch
14    implements DataPatchInterface,
15    PatchRevertableInterface
16{
17    /**
18     * @var ModuleDataSetupInterface
19     */
20    private $moduleDataSetup;
21
22    /**
23     * @param ModuleDataSetupInterface $moduleDataSetup
24     */
25    public function __construct(
26        ModuleDataSetupInterface $moduleDataSetup
27    ) {
28        /**
29         * If before, we pass $setup as argument in install/upgrade function, from now we start
30         * inject it with DI. If you want to use setup, you can inject it, with the same way as here
31         */
32        $this->moduleDataSetup = $moduleDataSetup;
33    }
34
35    /**
36     * @inheritdoc
37     */
38    public function apply()
39    {
40        $this->moduleDataSetup->getConnection()->startSetup();
41        //The code that you want apply in the patch
42        //Please note, that one patch is responsible only for one setup version
43        //So one UpgradeData can consist of few data patches
44        $this->moduleDataSetup->getConnection()->endSetup();
45    }
46
47    /**
48     * @inheritdoc
49     */
50    public static function getDependencies()
51    {
52        /**
53         * This is dependency to another patch. Dependency should be applied first
54         * One patch can have few dependencies
55         * Patches do not have versions, so if in old approach with Install/Ugrade data scripts you used
56         * versions, right now you need to point from patch with higher version to patch with lower version
57         * But please, note, that some of your patches can be independent and can be installed in any sequence
58         * So use dependencies only if this important for you
59         */
60        return [
61            SomeDependency::class
62        ];
63    }
64
65    public function revert()
66    {
67        $this->moduleDataSetup->getConnection()->startSetup();
68        //Here should go code that will revert all operations from `apply` method
69        //Please note, that some operations, like removing data from column, that is in role of foreign key reference
70        //is dangerous, because it can trigger ON DELETE statement
71        $this->moduleDataSetup->getConnection()->endSetup();
72    }
73
74    /**
75     * @inheritdoc
76     */
77    public function getAliases()
78    {
79        /**
80         * This internal method, that means that some patches with time can change their names,
81         * but changing name should not affect installation process, that's why if we will change name of the patch
82         * we will add alias here
83         */
84        return [];
85    }
86}

Reverting data patches#

Adobe Commerce and Magento Open Source do not allow you to revert a particular module data patch. However, you can revert all composer installed or non-composer installed data patches using the module:uninstall command.

Run the following command to revert all composer installed data patches:

bin/magento module:uninstall Vendor_ModuleName
CopyCopied to your clipboard
bin/magento module:uninstall Vendor_ModuleName

Run the following command to revert all non-composer installed data patches:

bin/magento module:uninstall --non-composer Vendor_ModuleName
CopyCopied to your clipboard
bin/magento module:uninstall --non-composer Vendor_ModuleName

Will old scripts work in newer versions?#

Old scripts will work with new versions of Magento. However, if you want to convert your old scripts to the new format, implement \Magento\Framework\Setup\Patch\PatchVersionInterface. This interface allows you to specify the setup version of the module in your database. If the version of the module is higher than or equal to the version specified in your patch, then the patch is skipped. If the version in the database is lower, then the patch installs.