[commits] [Wiki] changed: UpdatingYourDatabaseSchema

[Wiki Guest]

guest [178.26.86.13]  Sat, 20 Dec 2014 17:57:20 +0000

Modified page: http://wiki.horde.org/UpdatingYourDatabaseSchema
New Revision:  3
Change log:  made better understandable

@@ -2,36 +2,25 @@

  + 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

-control the migration process. File naming follows the pattern
+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.

-<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] part in the file name is not  
relevant and just supposed to indicate whether something is created or  
modified. Still, the horde applications all seem to make use of it.
+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.

-Inside the file there is a class defined which must be called
-<code type="shell">
-<Appname>[Base|Upgrade]<Name>
-</code>
+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.

-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
++ 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, you may run the CLI script horde-db-migrate, which  
should already be in your shell search path. The CLI is especially  
useful for re-running a migration script as horde will not notice a  
change in one of the migration files. the tool also accepts a revision  
number to set.
+++ 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.