Schema Updater

Table of Contents What is a Schema Updater? How Schema Updater's Work The Update Class Telling Your Module to Apply an Update(s)

What is a Schema Updater?

A Schema updater is a way for module developers to deploy updates to the data tables that their modules create. This is a particularly important when you need to update tables due to a new version of the module being released.

How Schema Updater's Work

A Schema Updater is specific to a particular module and therefor lives under the the module's directory in a sub-sudrectory called "updates".

When OWA is invoked the framework checks the required schema version of each active module against the current schema version number for each module.

When a new version of a module is created that requires an update to the module's schema, the module developer must author a Schema Updater class to bring the schema up to date.

The Update Class

Update classes can be authored by inheriting the owa_update abstract class and writing concrete version of the Up() and down methods.

OWA will attemp to apply updates found in a module's 'updates' sub-directory in sequential order. The order updates are applied is determined by the file name of the your update class (e.g. 002.php). These files names correspond to the version number of the schema that will be in place after the updates has been successfully applied. The sequential naming of files ensures that you never author two updates with the same name and eliminates the chance that updates are applied out of order.

Remember, OWA will apply your updates in sequential order - so the name of the file is critical to control which updates are to be applied first if the schema is more than one update behind. Update file names should only contain numbers.

Once your update is applied, OWA will store the new schema version as part of your module's configuration array in the database.

Update classes must be named according to an exact convention of: owa_{your module name}_{resulting schema version number with leading zeros}_update . See below for examples.

class owa_hello_002_update extends owa_update {

	function up() {
		
                // ...logic for update to version 2 of schema...

		// ensure that this method returns true if successful and false if not.
		return true;
		
		
	}
	
	function down() {
	
                // ...logic for reverting schema to version 1...

		// ensure that this method returns true if successful and false if not.
		return false;
	}

}

Telling Your Module to Apply an Update(s)

Every time you author a schema update you must tell your module that it now requires a new schema version in order for the update to be applied. To do so, change the 'required_schema_version' variable found in the constructor of your module's module.php file.

$this->required_schema_version = 4; // all updates less than this number will be applied if they have not already.

OWA will check this number against the version of the currently installed schema and apply all of the necessary updates required to bring the schema up to date.