Detailed Description

Abstract base class for database schema migrations.

Implementation of SchemaVersion interface using a database table.

This class serves as the abstract base class for all migrations.

Migrations can manage the evolution of a schema used by several physical databases. It's a solution to the common problem of adding a field to make a new feature work in your local database, but being unsure of how to push that change to other developers and to the production server. With migrations, you can describe the transformations in self-contained classes that can be checked into version control systems and executed against another database that might be one, two, or five versions behind.

General concept

Migrations can be described as a triple {sequence of migrations, current schema version, target schema version}. The migrations are "deltas" which are employed to change the schema of your physical database. They even know how to reverse that change. These behaviours are mapped to the methods #up and #down of class Migration. A migration is a subclass of that class and you define the behaviours by overriding methods #up and #down. Broadly spoken the current schema version as well as the target schema version are "pointers" into the sequence of migrations. When migrating the sequence of migrations is traversed between current and target version. If the target version is greater than the current version, the #up methods of the migrations up to the target version's migration are called. If the target version is lower, the #down methods are used.

Irreversible transformations

Some transformations are destructive in a manner that cannot be reversed. Migrations of that kind should raise an Exception in their #down method.

Example of use:

Create a directory which will contain your migrations. In this directory create simple php files each containing a single subclass of class Migration. Name this file with the following convention in mind:

(+)_([a-z_]+).php // (index)_(name).php

001_my_first_migration.php 002_another_migration.php 003_and_one_last.php

Those numbers are used to order your migrations. The first migration has to be a 1 (but you can use leading 0). Every following migration has to be the successor to the previous migration. No gaps are allowed. Just use natural numbers starting with 1.

When migrating those numbers are used to determine the migrations needed to fulfill the target version.

The current schema version must somehow be persisted using a subclass of SchemaVersion.

The name of the migration file is used to deduce the name of the subclass of class Migration contained in the file. Underscores divide the name into words and those words are then concatenated and camelcased.

Examples:

Name | Class

my_first_migration | MyFirstMigration another_migration | AnotherMigration and_one_last | AndOneLast

Those classes have to be subclasses of class Migration.

Example:

class MyFirstMigration extends Migration {

function description() {

put your code here

return migration description

}

function up() {

put your code here

create a table for example

}

function down() {

put your code here

delete that table

} }

After writing your migrations you can invoke the migrator as follows:

$path = '/path/to/my/migrations';

$verbose = TRUE;

instantiate a schema version persistor

this one is file based and will use a file in /tmp

$version = new FileSchemaVersion('/tmp');

$migrator = new Migrator($path, $version, $verbose);

now migrate to target version

$migrator->migrate_to(5);

If you want to migrate to the highest migration, you can just use NULL as parameter:

$migrator->migrate_to(NULL);

Author: mlunzena

Copyright: (c) Authors

This interface provides an abstract way to retrieve and set the current version of a schema. Implementations of this interface need to define where the version information is actually stored (e.g. in a file).