DatabaseSchemaUpdates
From AigaionWiki
Aigaion comes with a mechanism for automatically upgrading the database structure for new versions. If a table column has been added, or a certain user preference, or if all in the tables data should be converted because it is to be stored in a different format from now on, this mechanism ensures that the database is upgraded when somebody installs the new version of Aigaion (from a release, or from SVN).
This page documents that mechanism, to help developers understand how they should write such schema updates.
Contents |
How does it work?
For every database schema upgrade there is a separate function that makes the appropriate changes to the database. Such an schema update has a serial number.
When a new version of the Aigaion code has been installed, and an admin user logs in into Aigaion, the system will quickly check whether the latest schema update defined in the code has already been applied to the database. If not, all schema updates that had not yet been executed are applied to the database.
Which files and functions?
The schema update functions (with their serial numbers) are defined in "<aigaionroot>/helpers/schema_updates_v2_helper.php".
The check whether the latest schema update was performed is done in "<aigaionroot>/helpers/schema_helper.php".
How to add a schema update?
Take the following steps to add a schema update to Aigaion.
Write a schema update function
The function name is determined by its serial number; the function with the highest serial number must come first in the file "<aigaionroot>/helpers/schema_updates_v2_helper.php".
The basic template is as follows.
/**
Documentation of schema update
*/
function updateSchemaV2_42()
{
//Current database version already OK: return
if (checkVersion('V2.42', true))
{
return True;
}
//FIRST CHECK PREVIOUS VERSION, WHICH MIGHT ALSO NEED TO BE UPDATED
if (!updateSchemaV2_41())
{
return False;
}
//Execute the queries to modify the database schema and contents for the new version
...
... this may involve adding or removing tables and columns, or changing the
... current contents of certain fields...
...
//if any errors were encountered: fail...
if (!$succesfull)
{
return False;
}
//update successful: change current version number of database schema
return setVersion('V2.42');
}
If the schema update is made because a new sourceforge release of Aigaion is being prepared, use the following function setReleaseVersion($versionNumber,$updateType,$releaseNotes) (see example below).
The $updateType parameter takes an unordered list of any of the four update types bugfix, features, layout, and security.
//Execute the queries to modify the database schema and contents for the new version
...
if (!setReleaseVersion('5.7.12','bugfix,features,layout,security',"
Aigaion 5.7.12 is a non existing release. In this text you can add some notes to
describe the release; these notes will be shown on the 'about' page of Aigaion.
Formatting Rules for release notes:
* You cannot use HTML here
* Newlines will be replaced by html br-tags
"))
TEST EVERYTHING
Schema updates must be tested carefully. Ask other developers to test the update for you; test the update on your own computer a few times using test-installations of Aigaion, etcetera.
Enable the schema update function
In "<aigaionroot>/helpers/schema_helper.php", update the serial number in two places: in the checkVersion call and in the updateSchemaV2_nn call.