Understanding the flow of schema and data scripts

Simply put, the role of the schema scripts is to create a database structure supporting your module logic. For example, creating a table where our entities would persist their data. The role of the data scripts is to manage the data within existing tables, usually in the form of adding some sample data during module installation.

If we look a few steps back, we can notice how schema_version and data_version from the database match the setup_version number from our module.xml file. They all imply the same thing. If we were to now change the setup_version number in our module.xml file and run the php bin/magento setup:upgrade console command again, our database schema_version and data_version would get updated to this new version number.

This is done through module's install and upgrade scripts. If we take a quick look at the setup/src/Magento/Setup/Model/Installer.php file, we can see a function, getSchemaDataHandler, with content as follows:

private function getSchemaDataHandler($moduleName, $type)
{
    $className = str_replace('_', '\\', $moduleName) . '\Setup';
    switch ($type) {
        case 'schema-install':
            $className .= '\InstallSchema';
            $interface = self::SCHEMA_INSTALL;
            break;
        case 'schema-upgrade':
            $className .= '\UpgradeSchema';
            $interface = self::SCHEMA_UPGRADE;
            break;
        case 'schema-recurring':
            $className .= '\Recurring';
            $interface = self::SCHEMA_INSTALL;
            break;
        case 'data-install':
            $className .= '\InstallData';
            $interface = self::DATA_INSTALL;
            break;
        case 'data-upgrade':
            $className .= '\UpgradeData';
            $interface = self::DATA_UPGRADE;
            break;
        default:
            throw new \Magento\Setup\Exception("$className does not exist");
    }

    return $this->createSchemaDataHandler($className, $interface);
}

This is what tells Magento which classes to pick up and run from the individual module Setup directory. We will ignore the Recurring case for the moment, as only the Magento_Indexer module uses it.

For the first time, we run php bin/magento setup:upgrade against our module; while it still has no entries under the setup_module table, Magento will execute the files within the module Setup folder in following order:

• InstallSchema.php
• UpgradeSchema.php
• InstallData.php
• UpgradeData.php

Notice that this is the same order, top to bottom, as in the getSchemaDataHandler method.

Every subsequent upper module version number change, followed by the console php bin/magento setup:upgrade command, would result in the following files being run in the order as listed:

• UpgradeSchema.php
• UpgradeData.php

Additionally, Magento would record the upped version number under the setup_module database. Magento will only trigger install or upgrade scripts when the version number in the database is less than the version number in the module.xml file.

Tip

We are not required to always provide these install or upgrade scripts, if ever. They are only needed when we need to add or edit existing tables or entries in a database.

If we look carefully at the implementation of the install and update methods within the appropriate scripts, we can see they both accept ModuleContextInterface $context as a second parameter. Since upgrade scripts are the ones triggering on every upped version number, we can use $context->getVersion() to target changes specific to the module version.