Magento Setup Scripts

In this blog post we will see in detail how magento setup scripts work.

Basics

Setup scripts are located in “sql” and “data” folder for each module. These scripts are mainly used to run the install/upgrade process for each module mainly to set up sql table, entities etc. There are two types of files present in this “install” and “upgrade” file, we will see in detail how these work.

Inner Workings of Setup Scripts

Files to Refer
1. Mage_Core_Model_Resoure_Setup

The main entry point of setup scripts is at “run()” function in “Mage_Core_Model_App” class.
The first function to execute is

Mage_Core_Model_Resource_Setup::applyAllUpdates();

in the initModules() function and second is

Mage_Core_Model_Resource_Setup::applyAllDataUpdates();

Lets look into these functions in detail

1. applyAllUpdates()
This function first reads all ‘global/resources’ configuration, checks if it has setup->class. Create a new object of setup->class and calls “applyUpdates()” function in it.

This “applyUpdates()” is main function where all logic is written. This function first checks the installed db version of the module.
This information is stored in “core_resource” table. The install db version is then compared with the version stored in config.xml.
If installed version is empty then “_installResourceDb” is called, if installed version is lower then “_upgradeResourceDb” is called and if installed version is higher “_rollbackResourceDb” is called.

During installResouceDB():
1) It looks for files like install-{version}.php, install-{version}.sql, mysql4-install-{version}.php/sql file.
2) All install script files are taken in an array and it sorts the array with lower version at index 0 using version_compare function.
3) The current version number of the module is taken, the install script with the highest version number but less than equal to the module version number is taken. So finally we are left with only one install script file.
4) PHP files are directly included using “include” and “.sql” are executed directly using “multiQuery” function.
5) Version number is updated in the database as soon the script gets executed.
6) It then searches for “mysql4-upgrade-{version1}-{version2}”.php or “mysql4-upgrade-{version1}-{version2}”.sql files and taken them all in array.
7) Again files are sorted with lowest version number at index 0
8) Finally all version number files between current installed version number and config file version number are taken and executed.
9) Also after each install/upgrade script is executed, the corresponding version is update in database as well.

During _upgradeResourceDb():
Everything same as installResourceDB() except the install file is skipped and it take upgrade file greater then the current version number

During _rollbackResourceDb:
Same process as above except it looks for “mysql-rollback-{version1}-{version2}” file

Data Setup Scripts

We have another class of setup scripts called data scripts.
This is called from “Mage_Core_Model_App” ” Mage_Core_Model_Resource_Setup::applyAllDataUpdates();” function.
The format of data files is “data-install-{version}.php” and “data-upgrade-{version1}-{version2}.php”. This doesn’t support .sql format. These files are located either in folder “data” or “sql” inside the module.
These files are typically used to add data in tables create by install scripts. Rest of the process is exactly same as install scripts.

Common Functions Used In Setup Files

$installer->startSetup();
$installer->endSetup();

Usually setup process takes place between these two functions. “startSetup” removes all foreign key checks and auto increment values, “endSetup” adds it back

$installer->run(); 

We can specify multiple sql queries separated by ; to run

$this->getTable('core/url_rewrite')

Get Table Name of a model

$installer->getConnection()->addColumn('table_name', 'column_name', 'column_type');
$conn = $installer->getConnection();
$conn->dropKey($table, $key_name');
$installer->getConnection()->dropForeignKey('table', 'key_name');
$conn->dropColumn('table', 'column_name');