---
title: Codeigniter Database Migrations
author: geoff-doty
date: 2012-06-28
template: article.jade
---

##Overview

Migrations are a convenient way for you to alter your database in a structured and organized manner. You **could** edit fragments of SQL by hand but you would then be responsible for telling other developers that they need to go and run them and where they are located. 

Keeping track of which changes need to be run against which deployment environment also posses an equally challenging situation on every deployment.

Migrations **TRIES** to simplify this process by:

- Keeping All database changes in the Migrations Folder
- Versioning each Migration
- And allow you to account for environment variations


##How it works

Migrations are specially named CodeIgniter classes saved in the migrations folder…

    application/migrations

…that allow you to go up or down a migration revision. 

Migrations files are prefixed with a migration revision number, followed by a meaningful name:

    001_some_feature.php

The Migration class is named differently, so for the above file the migration class skeleton  would look like:

    class Migration_Some_Feature extends MY_Migrations {

    		public function up()
    		{
    			//code used to update the database
    		}
    		
    		public function down()
    		{
    		    //code to reverse what was done in the up() method
    		}
    }

A custome migration class (MY_Migration) could differ from the default implementation by providing an additional *protected* method

    _get_environment() {}

Added for connivence to organize settings based on environment.  The return values should be:

- development
- testing
- production

## Example
    class Migration_Some_Feature extends MY_Migrations {

    		public function up()
    		{
    			//global code used to update the database schema
    			
    			//environment specific changes
    			$environment = $this->_get_environment();
    			
    			if($environment) 
    			{
    			    switch($environment)
    			    {
    				    case 'development':
    			            //development settings changes here
    			            break;
    			            
    			        case 'testing':
    			           //testing settings changes here
    			           break;
    			           
    			       case 'production' :
    			           //production settings changes here
    			           break;
    			       default:
    						log_message('error','unable to determine environment');
    						return FALSE;  					           
    				 }
    			}
    			
              return TRUE;
    		}
    		
    		public function down()
    		{
    		    //code to reverse what was done in the up() method
    		}
    }

> __NOTE__
>> There are a more than few classes that can help with developing migrations:
    __dbforge()__  loaded by the migration class, can be used to create and delete tables
  - __active record__ can be used to do simple updates/deletes
  - __log_message()__ to log changes made to the database (console app in mac to watch)
  - ect..

## Configuration 

> Migrations are disabled by default

Migrations are managed via the migrations file:

    application/config/migrations.php

There are two settings of importance

    $config['migration_enabled'] = FALSE;
    $config['migration_version'] = 0;

**migration_enabled** switches database migrations on or off and the **migration_version** identifies the migration version this installation should use when triggered (see Updates and Rollbacks)

> While **migration_version** lists the target migration version, the current migration version is managed in the the *migrations.version* field in the database.  The Migration system automatically version up() or down() based on the version differences -- **WHEN TRIGGERED**!

## Updates and Rollbacks

Check out my custom `migrate` controller, it provides 4 operations

| Method  | Description |
|:--------|:------------|
| migrate/current | brings database to current version listed in config |
| migrate/ | alias for _migrate/current/__ |
| migrate/version/[num] | migrates to [num] revision passed in |
| migrate/latest | ignores config, and updates to latest migration file |

### Usage

Usage is _really_ split between to groups, __developers__ and __deployments__.

##### Developers Workflow

Developers should _NOT_ modify
​     
     config/migrations.php

Instead, developers should manage their local database via
- _migrate/latest_ to load the latest migration file on their system 
- or _migrate/version/[num]_ to go to a migration version to test

##### Deployment Workflow

When setting up a deployment, the _config/migrations.php_ would be modified to reflect the version you want that deployment set to:

    $config['migration_version'] = 121;  //used migration version

and then run

    migrate/current
---


> There currently is no UI, however one could be build based on the return values of the _migrate_ methods.

>> Return values:
- TRUE, If Migration is on the latest version
- FALSE, If the migration failed
- INT, revision number successfully updated to 


##Additional Resources
- [Migrations CodeIgniter Manual](http://codeigniter.com/user_guide/libraries/migration.html)  
- [DBForge Manual](http://codeigniter.com/user_guide/database/forge.html)
- [Active Record Manual](http://codeigniter.com/user_guide/database/active_record.html)