I often hear/read that when getting issue with Magento 2 there is a magic solution, running setup:upgrade command. Probably that this command solves many troubles you can get, but how ? What’s inside that could lead to solve your issue ?

Let’s take a closer look at the content of this command.

# setup/src/Magento/Setup/Console/Command/UpgradeCommand.php
$installer->updateModulesSequence($keepGenerated);
$installer->installSchema($request);
$installer->installDataFixtures($request);

1. updateModulesSequence

# setup/src/Magento/Setup/Model/Installer.php:updateModulesSequence
$this->cleanCaches();

1. Cache dir is cleaned: /var/cache/

# setup/src/Magento/Setup/Model/Installer.php:updateModulesSequence
if (!$keepGeneratedFiles) {
    $this->cleanupGeneratedFiles();
}

2. Generated files are cleaned if option –keep-generated is not used.
What “generated” files corresponds to ? All files that are subject of code generation: code-generated classes and materialized static view files.

• var/generated/code/
• var/generated/metadata/
• var/view_preprocessed/
• pub/static/

# setup/src/Magento/Setup/Model/Installer.php:updateModulesSequence
$this->createModulesConfig([])

3. app/etc/config.php file is generated

2. installSchema

# setup/src/Magento/Setup/Model/Installer.php:installSchema
$this->assertDbConfigExists();
$this->assertDbAccessible();
$setup = $this->setupFactory->create($this->context->getResources());
$this->setupModuleRegistry($setup);
$this->setupCoreTables($setup);
$this->log->log('Schema creation/updates:');
$this->declarativeInstallSchema($request);
$this->handleDBSchemaData($setup, 'schema', $request);
/** @var Mysql $adapter */
$adapter = $setup->getConnection();
$schemaListener = $adapter->getSchemaListener();

if ($this->convertationOfOldScriptsIsAllowed($request)) {
    $schemaListener->setResource('default');
    $this->schemaPersistor->persist($schemaListener);
}

1. A verification is made to ensure database config is set (assertDbConfigExists) and a connection can be established (assertDbAccessible).

2. An other verification is made to check if setup_module (setupModuleRegistry) and other core tables (session, cache, cache_tag, flag) are existing (setupCoreTables)

3. Declarative schemas are installed (declarativeInstallSchema). It’s the step where database tables are created/updated

4. Finally for each modules:

• Old schema install scripts are installed/updated (handleDBSchemaData and getSchemaListener);
  If –convert-old-scripts command option is used then old scripts will be converted to new db_schema.xml format (convertationOfOldScriptsIsAllowed)
• Setup version are updated in database
• Schema patches are applied by PatchApplier
• Recurring schema scripts are executed

3. installDataFixtures

# setup/src/Magento/Setup/Model/Installer.php:installSchema
$this->assertDbConfigExists();
$this->assertDbAccessible();
$setup = $this->dataSetupFactory->create();
$this->checkFilePermissionsForDbUpgrade(); 
$this->log->log('Data install/update:');
$this->handleDBSchemaData($setup, 'data', $request);

1. As for installSchema step, tests to database are run

2. Permission to write in app/etc/ and var/ directories is checked

3. Finally for each modules:

• Old data scripts are installed/updated.
• Data version are updated in database
• Data patches are applied by PatchApplier
• Recurring data scripts are executed

4. Configs are imported

If needed, app:config:import is executed in order to update Magento configurations.

Configurations are read from config.php and env.php files and saved in flag table into system_config_snapshot row.
A hash of this config is also saved into config_hash row during app:config:dump.
It’s that hash which will be used by the changeDetector to determine if configurations has been changed, and in this case execute the config import command.