172 lines
5.3 KiB
Markdown
172 lines
5.3 KiB
Markdown
---
|
||
title: Codeigniter Database Migrations
|
||
author: geoff-doty
|
||
date: 2012-06-28
|
||
template: article.jade
|
||
---
|
||
|
||
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
|
||
|
||
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)
|
||
|
||
|
||
|