6.0.0-git
2018-12-09
Last Modified 2014-12-20 by Guest

Migration Mechanism

When you take your application to a new revision, you may whish to change your SQL database schema. Tables may be added or removed and columns in a table may be added or removed. For this, horde provides the migration mechanism.

Files

Files under <appname>/migration/ control the migration process. File naming follows the pattern <n>_<appname>_[base|upgrade]_<name>.php with n being a decimal number and name an arbitrary name.

Inside the file there is a class defined which must be called <Appname>[Base|Upgrade]<Name> where Name matches the one used for file naming. Note that the file name is all lowercase and the class name is CamelCase.

It appears that the [base|upgrade] part in the name is just a convention that will not be enforced. Still, the horde applications all seem to make use of it.

The class may define an "up" method for upgrading and a "down" method for downgrading the application. The methods may implement practically any necessary action. For instance, the down method may drop a database table when the application is to be removed from the system. For implementation of the methods feel free to steal code from one of the existing horde applications.

Usage

Admin Console

When you use the admin console, horde determines if the revision number of your application matches the highest number of migration files found. If not, the console notifies you ("DB schema needs update") and lets you trigger the migration process with the click of a button. All migration files with numbers between the current revision and the highest number found in a file name will the be considered and the up-methods of those files will be called. The revision number of your application will be set accordingly. Note that this revision number is not the same as the version number of your application defined in <application>/lib/Application.php.

CLI Tool

Alternatively, you may run the CLI script horde-db-migrate, which should already be in your shell search path. The CLI tool is especially useful for running a migration script repeatedly (such as during development) as horde will not notice a change in a migration file. The CLI tool also lets you set your database schema to a defined revision number.