Magento2 What's the point of having both InstallSchema and UpgradeSchema

Question

If UpgradeSchema/UpgradeData are executed when installing and upgrading a module what's the point of having InstallSchema/InstallData (besides just having a well-named file that is only executed once). We could handle the install part in the Upgrade file as well - we could check !$context->getVersion().

This raises another question about the correct workflow for the lifetime of a module.

Do we create the Install* script only once and then never change it? I've seen third party modules changing this file between versions. In that case I assume they also track the same changes in Upgrade* (hence duplicating code).

Am I missing something here? Thanks!

UPDATE: I understand the role of each file and the differences between Schema and Data. I'm interested to find out about best practices. My understanding is we're allowed to update Install* as long as the module is in development but once it's made public we're not allowed to change this file ever again. From that point on we should only use versioned Upgrade* scripts. Is this correct?

Answer 1

I got this question in a training I was giving, and we tried out if we need InstallSchema / InstallData at all. It turned out we don't need it, as the Upgrade classes are executed on installation too. So, in my opinion, I would not use the Install classes at all as the distinction is quite arbitrary and it only confuses in most cases.

Answer 2

There is no relevant for the word "upgrade" if there is nothing "installed". So what we are upgrading is something which exist (or installed). So literally it makes sense to have one install schema and then many upgrade schema.

Ideally an install schema should hold the basic entity table definition (if your module is associated with any custom entities) or the attribute definition (if your module is associated with existing eav entities). So it holds the skeleton of your module's database relation.

While you developing or after releasing your module, you will come across to several occasions where you need to change this skeleton. In that case, you should use an upgrade schema.

So in effect you should have one install schema and multiple upgrade schema.

Answer 3

Both are used as the file names suggest

InstallSchema

Schema setup scripts change database schema, they create or change needed database tables. If module is installing, Setup\InstallSchema::install() is executed.

<?php 

namespace Vendor\ModuleName\Setup;

use Magento\Framework\Setup\InstallSchemaInterface;
use Magento\Framework\Setup\SchemaSetupInterface;
use Magento\Framework\Setup\ModuleContextInterface;

class InstallSchema implements InstallSchemaInterface
{
    public function install(SchemaSetupInterface $setup, ModuleContextInterface $context)
    {
        $setup->startSetup();

        $table = $setup->getConnection()->newTable(
            $setup->getTable('my_module_table')
        )->addColumn(
            'custom_id',
            \Magento\Framework\DB\Ddl\Table::TYPE_INTEGER,
            null,
            ['identity' => true, 'unsigned' => true, 'nullable' => false, 'primary' => true],
            'Custom Id'
        )->addColumn(
            'name',
            \Magento\Framework\DB\Ddl\Table::TYPE_TEXT,
            255,
            [],
            'Custom Name'
        )->setComment(
            'Custom Table'
        );
        $setup->getConnection()->createTable($table);

        $setup->endSetup();
    }
}

UpgradeSchema

If module is installing or upgrading, Setup\UpgradeSchema::upgrade() is executed. All versions are handled in this file itself you dont have to create version upgrades files like in M1.

namespace Vendor\ModuleName\Setup;

use Magento\Framework\Setup\UpgradeSchemaInterface;
use Magento\Framework\Setup\SchemaSetupInterface;
use Magento\Framework\Setup\ModuleContextInterface;

class UpgradeSchema implements UpgradeSchemaInterface
{
    public function upgrade(SchemaSetupInterface $setup, ModuleContextInterface $context)
    {
        $setup->startSetup();

        //handle all possible upgrade versions

        if (version_compare($context->getVersion(), '1.0.1') < 0) {
            //code to upgrade to 1.0.1
            //you can add, update or drop tables from here
        }

        if (version_compare($context->getVersion(), '1.0.2') < 0) {
            //code to upgrade to 1.0.2
            //you can add, update or drop tables from here
        }

        $setup->endSetup();
    }
}