Yii DB Migrations

A database migrations engine for the Yii framework. It comes in the form of an extension which can be dropped into any existing Yii framework application.

It relies on the database abstraction layer of the Yii framework to talk to the database engine.

It’s largely inspired on the migrations functionality of the Ruby on Rails framework.

Why bother in the first place?

You might wonder why you need database migrations in the first place. Sure, you could use plain SQL files to apply updates to the database, but they have a big disadvantage: they are database specific.

Imagine you initially create your database using SQLite and later on decide to change to MySQL. When you use plain SQL files, you will need to rewrite them using MySQL’s flavor of SQL. Also, you will need to create some tool that knows what has been applied already to the database and what’s not applied yet.

Meet database migrations. By defining a higher level interface to creating and maintaining the database schema, you can define it in a database agnostic way.

By using PHP functions to create tables, indexes, fields, … you can write the schema once and apply it to any database backend supported. The added bonus is that the yii-dbmigrations extension keeps track of which migrations have been applied already and which ones still need to be applied.

Current limitations

Be aware that the current version is still very alpha.

There are only two database engines supported:

• MySQL
• SQLite

Installing the extension

Putting the files in the right location

Installing the extension is quite easy. Once you downloaded the files from github, you need to put all the files in a folder called “yii-dbmigrations” and put it in the protected/extensions folder from your project.

Configuring the database connection

You need to make sure you configure database access properly in the configuration file of your project. As the console applications in the Yii framework look at the protected/config/console.php file, you need to make sure you configure the db settings under the components key in the configuration array. For MySQL, the configuration will look as follows:

'components' => array(
    'db'=>array(
        'class' => 'CDbConnection',
        'connectionString'=>'mysql:host=localhost;dbname=my_db',
        'charset' => 'UTF8',
        'username'=>'root',
        'password'=>'root',
    ),
),

For SQLite, the configuration looks as follows:

'components' => array(
    'db'=>array(
        'connectionString'=>'sqlite:'.dirname(__FILE__).'/../data/my_db.db',
    ),
),

Configuring the command map

To make the yiic tool know about the migrate command, you need to add a commandMap key to the application configuration in protected/config/console.php.

In there, you need to put the following configuration:

'commandMap' => array(
    'migrate' => array(
        'class'=>'application.extensions.yii-dbmigrations.CDbMigrationCommand',
    ),
),

Testing your installation

To test if the installation was succesfull, you can run the yiic command and should see the following output:

Yii command runner (based on Yii v1.0.6)
Usage: protected/yiic <command-name> [parameters...]

The following commands are available:
 - migrate
 - message
 - shell
 - webapp

To see individual command help, use the following:
   protected/yiic help <command-name>

It should mention that the migrate command is available.

Creating migrations

Naming conventions

You can create migrations by creating files in the protected/migrations folder or in the migrations folder inside your module. The file names for the migrations should follow a specific naming convention:

m20090614213453_MigrationName.php

The migration file names always start with the letter m followed by 14 digit timestamp and an underscore. After that, you can give a name to the migration so that you can easily identify the migration.

Implementing the migration

In the migration file, you need to create a class that extends the parent class CDbMigration. The CDbMigration class needs to have the up and down methods as you can see in the following sample migration:

class m20090611153243_CreateTables extends CDbMigration {

    public function up() {

        $this->createTable(
            'posts',
            array(
                array('id', 'primary_key'),
                array('title', 'string'),
                array('body', 'text'),
            )
        );

        $this->addIndex(
            'posts', 'posts_title', array('title')
        );

    }

    public function down() {
        $this->removeTable('posts');
    }

}

Supported functionality

In the migration class, you have the following functionality available:

• execute: execute a raw SQL statement that doesn’t return any data.
• query: execute a raw SQL statement that returns data.
• createTable: create a new table
• renameTable: rename a table
• removeTable: remove a table
• addColumn: add a column to a table
• renameColumn: rename a column in a table
• changeColumn: change the definition of a column in a table
• removeColumn: remove a column from a table
• addIndex: add an index to the database or table
• removeIndex: remove an index from the database or table

When specifying fields, we also support a type mapping so that you can use generic type definitions instead of database specific type definitions. The following types are supported:

• primary_key
• string
• text
• integer
• float
• decimal
• datetime
• timestamp
• time
• date
• binary
• boolean
• bool

You can also specify a database specific type when defining a field, but this will make your migrations less portable across database engines.

Applying migrations

Once you created the migrations, you can apply them to your database by running the migrate command:

protected/yiic migrate

You will see the following output:

Creating initial schema_version table
Applying migration: m20090611153243_CreateTables
    >> Creating table: posts
    >> Adding index posts_title to table: posts
Marking migration as applied: m20090611153243_CreateTables
Applying migration: m20090612162832_CreateTags
    >> Creating table: tags
    >> Creating table: post_tags
    >> Adding index post_tags_post_tag to table: post_tags
Marking migration as applied: m20090612162832_CreateTags
Applying migration: m20090612163144_RenameTagsTable
    >> Renaming table: post_tags to: post_tags_link_table
Marking migration as applied: m20090612163144_RenameTagsTable
Applying migration: m20090616153243_Test_CreateTables
    >> Creating table: test_pages
    >> Adding index test_pages_title to table: test_pages
Marking migration as applied: m20090616153243_Test_CreateTables

It will apply all the migrations found in the protected/migrations directory provided they were not applied to the database yet.

It will also apply any migrations found in the migrations directory inside each module which is enabled in the application.

If you run the migrate command again, it will show that the migrations were applied already:

Skipping applied migration: m20090611153243_CreateTables
Skipping applied migration: m20090612162832_CreateTags
Skipping applied migration: m20090612163144_RenameTagsTable
Skipping applied migration: m20090616153243_Test_CreateTables

Since the migrate command checks based on the ID of each migration, it can detect that a migration is already applied to the database and therefor doesn’t need to be applied anymore.

Author information

This extension is created and maintained by Pieter Claerhout. You can contact the author on:

• Website: http://www.yellowduck.be
• Twitter: http://twitter.com/pieterclaerhout
• Github: http://github.com/pieterclaerhout/yii-dbmigrations/tree/master