Diff for UpdatingYourDatabaseSchema between 2 and 3

[[toc]]

+ 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
<code type="shell">	
<appname>/migration/
</code>+ Files

controlFiles 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. 

<code type="shell">		
<n>_<appname>_[base|upgrade]_<name>.php
</code>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]{{[base|upgrade]}} part in the file name is just a convention that will not relevant and just supposed to indicate whether something is created or modified.be enforced. Still, the horde applications all seem to make use of it.

Inside the file there is aThe class defined which mustmay 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 called 
<code type="shell">
<Appname>[Base|Upgrade]<Name>
</code>removed from the system. For implementation of the methods feel free to steal code from one of the existing horde applications.

Note that the file name is all lowercase and the class name is CamelCase. The class may define an "up" for upgrading an installation and a "down" method for removing the installation, for instance if you which to remove your application from the horde system. For implementation of the methods feel free to steal code from one of the existing horde applications.
Usage

+++ Usage

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 will not necessarily match the version number defined in++ Admin Console

<code type="shell">
<application>/lib/Application.php
</code>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}}.

Alternatively,++ CLI Tool

Alternatively, you may run the CLICLI script horde-db-migrate,{{horde-db-migrate}}, which should already be in your shell search path. The CLI tool is especially useful for re-runningrunning a migration script repeatedly (such as during development) as horde will not notice aa change in one of thea migration files. thefile. The CLI tool also acceptslets you set your database schema to a defined revision number to set.number.