When customising Mahara it is sometimes necessary to make changes to the database during installation of a site, and make upgrades to your database customisations.
From Mahara 1.2, site-specific database changes can be kept separated from core install/upgrade code by placing custom install/upgrade code into the /local directory, the same way Moodle does it. This allows local customisations to use a separate series of database version numbers to the one used by the Mahara core.
Custom php code to alter the database goes in htdocs/local/install.php and htdocs/local/upgrade.php.
The local_preinst() function gets run after the core database tables have been set up, and before the plugin tables are set up; and local_postinst() is run at the very end of the installation, after all the database tables have been created, after the admin user has been created, and just before the admin user is logged in. We may add more hooks in this file later as required.
version.php and upgrade.php work the same way as in the Mahara core. When the admin/upgrade.php page is hit, the local code version number (in local/version.php) is compared against the 'localversion' in the database's config table. If the code is newer than the database, then the xmldb_local_upgrade function (in local/upgrade.php) is run, and passed the database 'localversion'. Code placed in here should test the database version against the code version. Look in /htdocs/lib/db/upgrade.php for examples of how it looks for the core.