How to use setup scripts for your module?

From Magento 1.6 and upwards you don't need to use mysql4 anymore because of added multi-RDBMS support.

To find out why it's not running, you can check the exception.log or system.log, maybe Magento coudn't find your setup class. Creating an install script is pretty straightforward though.

Also check Alan Storm's guide: http://alanstorm.com/magento_setup_resources

As @erfan saif, magento got multi-rdbms support since 1.6. But in the real world, I know only mysql backends.

It is important to understand, that magento can have different install/upgrade/data scripts for different backends. If you want a special Index-Type which is supported by mysql but not by standard-SQL you can implement a mysql4-install-1.0.0.php script. If your script is generic, use install-1.0.0.php

If you take a look into Mage_Core_Model_Resource_Setup I can find two interessting things:

1. You can name your files (%s-)%s-VERSION.(php|sql)
2. If you have two install scripts (but with data scripts, it is the same (app/code/core/Mage/Core/Model/Resource/Setup.php:520)) magento prefers the specialised script over the generic script (as one would expect)

app/code/core/Mage/Core/Model/Resource/Setup.php:488

$regExpDb   = sprintf('#^%s-(.*)\.(php|sql)$#i', $actionType);
$regExpType = sprintf('#^%s-%s-(.*)\.(php|sql)$#i', $resModel, $actionType);

while (false !== ($file = $handlerDir->read())) {
    $matches = array();
    if (preg_match($regExpDb, $file, $matches)) {
        $dbFiles[$matches[1]] = $filesDir . DS . $file;
    } else if (preg_match($regExpType, $file, $matches)) {
        $typeFiles[$matches[1]] = $filesDir . DS . $file;
    }
}
[...]
foreach ($typeFiles as $version => $file) {
    $dbFiles[$version] = $file;
}

Be careful, if you name your script .sql it is invoked directly into the database:

// app/code/core/Mage/Core/Model/Resource/Setup.php:621
switch ($fileType) {
    case 'php':
        $conn   = $this->getConnection();
        $result = include $fileName;
        break;
    case 'sql':
        $sql = file_get_contents($fileName);
        if (!empty($sql)) {

            $result = $this->run($sql);

Also, what can I do when my setup script is not running to find out why it is not?

I prefer a die('sadf') at the beginning of my install/upgrade file, because I can run it multiple times if it is called, so I can check, wether all the variables I set are correct, before anything is changed in the database. If I see the 'sadf' on the screen, I know, the script is running.

I magento loads (instead of the sadf), it is time to debug, my two standard errors are:

1. I have forgotton to add the script to the config
2. I have the directory in sql/ forgotten, e.g. sql/install-1.0.0.php instead of sql/my_module_setup/install-1.0.0.php

And because I think it fits here, be careful with your variable names: http://blog.fabian-blechschmidt.de/articles/file-kills-setup-script.html

UPDATE @rouven-rieker added via twitter that data- and missing mysql4- was added in magento 1.6. If you need backwards compatibility be careful!

If your script isn't running you should also check if your modules version matches the version of your setup-script.

<modules>
    <Your_Module>
        <version>0.0.1</version>
    </Your_Module>
</modules>