+ +
+

Migrations Class

+

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. You would also have to keep track of which changes +need to be run against the production machines next time you deploy.

+

The database table migration tracks which migrations have already been +run so all you have to do is update your application files and +call $this->migration->current() to work out which migrations should be run. +The current version is found in application/config/migration.php.

+ +
+

Migration file names

+

Each Migration is run in numeric order forward or backwards depending on the +method taken. Two numbering styles are available:

+
    +
  • Sequential: each migration is numbered in sequence, starting with 001. +Each number must be three digits, and there must not be any gaps in the +sequence. (This was the numbering scheme prior to CodeIgniter 3.0.)
    • +
  • Timestamp: each migration is numbered using the timestamp when the migration +was created, in YYYYMMDDHHIISS format (e.g. 20121031100537). This +helps prevent numbering conflicts when working in a team environment, and is +the preferred scheme in CodeIgniter 3.0 and later.
    • +
+

The desired style may be selected using the $config['migration_type'] +setting in your application/config/migration.php file.

+

Regardless of which numbering style you choose to use, prefix your migration +files with the migration number followed by an underscore and a descriptive +name for the migration. For example:

+
    +
  • 001_add_blog.php (sequential numbering)
    • +
  • 20121031100537_add_blog.php (timestamp numbering)
    • +
+
+
+

Create a Migration

+

This will be the first migration for a new site which has a blog. All +migrations go in the application/migrations/ directory and have names such +as 20121031100537_add_blog.php.

+
<?php
+
+defined('BASEPATH') OR exit('No direct script access allowed');
+
+class Migration_Add_blog extends CI_Migration {
+
+        public function up()
+        {
+                $this->dbforge->add_field(array(
+                        'blog_id' => array(
+                                'type' => 'INT',
+                                'constraint' => 5,
+                                'unsigned' => TRUE,
+                                'auto_increment' => TRUE
+                        ),
+                        'blog_title' => array(
+                                'type' => 'VARCHAR',
+                                'constraint' => '100',
+                        ),
+                        'blog_description' => array(
+                                'type' => 'TEXT',
+                                'null' => TRUE,
+                        ),
+                ));
+                $this->dbforge->add_key('blog_id', TRUE);
+                $this->dbforge->create_table('blog');
+        }
+
+        public function down()
+        {
+                $this->dbforge->drop_table('blog');
+        }
+}
+
+
+

Then in application/config/migration.php set $config['migration_version'] = 20121031100537;.

+
+
+

Usage Example

+

In this example some simple code is placed in application/controllers/Migrate.php +to update the schema.:

+
<?php
+
+class Migrate extends CI_Controller
+{
+
+        public function index()
+        {
+                $this->load->library('migration');
+
+                if ($this->migration->current() === FALSE)
+                {
+                        show_error($this->migration->error_string());
+                }
+        }
+
+}
+
+
+
+
+

Migration Preferences

+

The following is a table of all the config options for migrations.

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PreferenceDefaultOptionsDescription
migration_enabledFALSETRUE / FALSEEnable or disable migrations.
migration_pathAPPPATH.’migrations/’NoneThe path to your migrations folder.
migration_version0NoneThe current version your database should use.
migration_tablemigrationsNoneThe table name for storing the schema +version number.
migration_auto_latestFALSETRUE / FALSEEnable or disable automatically +running migrations.
migration_type‘timestamp’‘timestamp’ / ‘sequential’The type of numeric identifier used to name +migration files.
+
+
+

Class Reference

+
+
+class CI_Migration
+
+
+current()
+
+++ + + + + + +
Returns:TRUE if no migrations are found, current version string on success, FALSE on failure
Return type:mixed
+

Migrates up to the current version (whatever is set for +$config['migration_version'] in application/config/migration.php).

+
+ +
+
+error_string()
+
+++ + + + + + +
Returns:Error messages
Return type:string
+

This returns a string of errors that were detected while performing a migration.

+
+ +
+
+find_migrations()
+
+++ + + + + + +
Returns:An array of migration files
Return type:array
+

An array of migration filenames are returned that are found in the migration_path property.

+
+ +
+
+latest()
+
+++ + + + + + +
Returns:Current version string on success, FALSE on failure
Return type:mixed
+

This works much the same way as current() but instead of looking for +the $config['migration_version'] the Migration class will use the very +newest migration found in the filesystem.

+
+ +
+
+version($target_version)
+
+++ + + + + + + + +
Parameters:
    +
  • $target_version (mixed) – Migration version to process
    • +
+
Returns:

TRUE if no migrations are found, current version string on success, FALSE on failure

+
Return type:

mixed

+
+

Version can be used to roll back changes or step forwards programmatically to +specific versions. It works just like current() but ignores $config['migration_version'].

+
$this->migration->version(5);
+
+
+
+ +
+ +
+
+ + +