Data Patches

A data patch is a PHP class that changes the contents of the database once. It inserts a CMS block, corrects a configuration value, or fills in a column that a schema change just added. It lives in one fixed place, app/code/Vendor/Module/Setup/Patch/Data/, and implements Magento\Framework\Setup\Patch\DataPatchInterface. Nothing registers it: Magento reads that directory for every enabled module.

How Magento knows it already ran

When a patch finishes, Magento inserts its fully qualified class name into the patch_list table. That table has two columns, patch_id and patch_name. On the next run the name is found and the patch is skipped. There is no version number and no module column, only the class name.

Patches are applied by bin/magento setup:upgrade, or by bin/magento setup:db-data:upgrade on its own. Adding the file changes nothing until one of those runs. bin/magento setup:db:status tells you whether anything is pending.

What they replaced

Magento 2.3 introduced patches. Before that a module shipped InstallData.php and UpgradeData.php, and Magento compared the module's setup_version with the setup_module table to decide what to run. Patches replaced both mechanisms. setup_version in module.xml is no longer the trigger for anything, and a new module does not need the attribute at all.

What trips people up

A data patch runs inside a single database transaction. If it throws, everything rolls back and no row reaches patch_list, so fixing the cause and running setup:upgrade again is safe. To force a re-run on a development machine, delete the row from patch_list.

<?php
// app/code/Acme/Shipping/Setup/Patch/Data/DisableFlatRateCarrier.php
declare(strict_types=1);

namespace Acme\Shipping\Setup\Patch\Data;

use Magento\Framework\App\Config\Storage\WriterInterface;
use Magento\Framework\Setup\Patch\DataPatchInterface;

class DisableFlatRateCarrier implements DataPatchInterface
{
    private WriterInterface $configWriter;

    public function __construct(WriterInterface $configWriter)
    {
        $this->configWriter = $configWriter;
    }

    public function apply(): self
    {
        // WriterInterface::save($path, $value, $scope = 'default', $scopeId = 0)
        $this->configWriter->save('carriers/flatrate/active', '0');

        return $this;
    }

    public static function getDependencies(): array
    {
        return [];
    }

    public function getAliases(): array
    {
        return [];
    }
}

// Apply it:
//   bin/magento setup:upgrade
//   bin/magento cache:flush config
//
// setup:upgrade writes one row into core_config_data and inserts
// Acme\Shipping\Setup\Patch\Data\DisableFlatRateCarrier into patch_list.
// A second setup:upgrade finds that row and skips the patch.
// Without the cache flush, the admin and storefront keep reading the
// old value from the config cache.

-- The whole record of which patches have run.
SELECT patch_id, patch_name
FROM patch_list
WHERE patch_name LIKE 'Acme\\\\%'
ORDER BY patch_id;

-- Force one patch to run again on a development database.
DELETE FROM patch_list
WHERE patch_name = 'Acme\\Shipping\\Setup\\Patch\\Data\\DisableFlatRateCarrier';

<?xml version="1.0"?>
<!-- app/code/Acme/Shipping/etc/module.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Acme_Shipping">
        <sequence>
            <module name="Magento_OfflineShipping"/>
        </sequence>
    </module>
</config>