Bonfire Migrations

1 What are Migrations?

Migrations are simple files that hold the commands to apply and remove changes to your database. This allows you and your team to easily keep track of changes made for each new module. They may create tables, modify tables or fields, etc. But they are not limited to just changing the schema. You could use them to fix bad data in the database or populate new fields.

While you could make the changes to the database by hand, migrations provide a simple, consistent way for developers to stay on track with each other's changes. It also makes it simple to apply the changes in your development environment to your production environment.

Using migration files also creates a version of your database that can be included in your current code versioning, whether you use git, svn, or another solution. While you might not have your data backed up in the case of a devastating loss, you can at least recreate your database and start over.

Migrations are contained in sequentially numbered files so the system knows the order to apply them or remove them.

2 Migrations Spheres

Bonfire recognizes three distinct areas where migrations can be applied: Core, Application, and Module. All of the files are exactly the same structure, but are placed in different areas to allow you to keep your numbering systems separate.

2.1 Core Migrations

Core migrations are files that are necessary for the database schema of Bonfire core. This keeps any Bonfire updates completely separate from your application's needs, and helps to remove any conflict between your own migration file numbers and Bonfire's.

These are stored under application/db/migrations/core.

2.2 Application Migrations

For your own application, you should use application-level migrations. This is the perfect place for changes apply to application-specific changes. However, if you are planning on re-using modules from one application to the next, you should consider placing them at the module level.

These migration files are stored under application/db/migrations.

2.3 Module Migrations

Each module can contain its own migrations, that can be applied completely separate of any application or core migrations. This allows for you to easily re-use your modules in other applications.

Module-level migrations are stored in modules/my_module/migrations.

3 Migration Types

Unlike the migrations that CodeIgniter provides, Bonfire’s migrations support two different types of migration files, allowing you to work the way that works best for you.

• dbForge migrations are the standard CodeIgniter migrations. They are completely self-contained and all code that is to be run for the migration to happen is contained within the up() and down() methods.
• SQL migrations are a unique addition to Bonfire. They allow you to use raw SQL commands instead of dbforge/dbutil commands that are sometimes unwieldy. SQL migrations are best used when you know that you will only be using MySQL databases and can customize your SQL commands to that database.

4 Enabling Migrations

A clean install has migrations enabled by default. However, it is recommended when you move to production to disable migrations for security.

To disable migrations, edit the following line in application/core modules/migrations/config/migrations.php to be false.

	$config['migrations_enabled'] = true;

5 Anatomy of a Migration

A migration is a subclass of Migration that implements two methods: up (perform the required transformations) and down (revert them). Within each migration you can use any of the methods that CodeIgniter provides, like the dbutils and dbforge classes.

6 Creating a Migration

6.1 File Name

Migration files MUST be numbered sequentially. The rest of the file name is up to you, but it is recommended that the name describe what actually happens in the file. Like Install_initial_tables, Permissions_upgrade, etc. It must end with the .php extension.

001_Install_initial_tables.php
002_Version_02_upgrades.php
003_Permissions_upgrade.php

6.2 File Structure

The file is a standard PHP class, that must follow three simple rules:

• The class must be named the same as the file, except the number is replaced by Migration. For a file named001_Install_initial_tables.php, the class would be named Migration_Install_initial_tables. The name is case-sensitive.
• The class MUST extend the Migration class
• The class MUST include two methods: up() and down(). As the names imply, the up() method is ran whenever you are migrating up to that version. The down() method is ran whenever uninstalling that migration.

6.3 A Skeleton Migration

class Migration_Install_initial_tables extends Migration {

  function up() {
      ...
  }

  //--------------------------------------------------------------------

  function down() {
      ...
  }

  //--------------------------------------------------------------------
}

6.4 SQL Migrations

When creating a SQL migration, there are two changes that you must make to the above skeleton.

• You must provide a class variable named $migration_type that is equal to sql.
• In both the up() and down() methods, you must return your SQL commands as a single string. This SQL may contain multiple commands, as long as they are separated by a colon.

class Migration_Install_initial_tables extends Migration {

  public $migration_type = 'sql';

  function up() {
      $sql = "...";

      return $sql;
  }

  //--------------------------------------------------------------------

  function down() {
      $sql = "...";

      return $sql;
  }

  //--------------------------------------------------------------------
}

When writing raw SQL queries you must take into account the database prefix for your installation. This can be found with a small piece of code:

	$prefix = $this->db->dbprefix;

In your queries you would use it like:

	$sql = "ALTER TABLE `{$prefix}activities` ADD COLUMN `deleted` TINYINT(12) DEFAULT '0' NOT NULL AFTER `created_on`";

7 Running Migrations

Migrations can be run, both up and down, in the Bonfire admin pages. You can find them under Database / Database Tools / Migrations.

7.1 Auto-Running Migrations

Migrations can be set to auto-run when discovered by changing a couple of lines in the application/config/config.php file. At the bottom of the file you'll find the following lines.

$config['migrate.auto_core']  = TRUE;
$config['migrate.auto_app']   = FALSE;

migrate.auto_core, when set to TRUE, will run a check for new migrations for Bonfire Core on every page load.

migrate.auto_app, when set to TRUE, will run a check for new migrations for your application-specific migrations on every page load.

These are very handy to have set to TRUE in both Development and Staging/Test environments, but will slow your site down some since they check on every page load. It is recommended that Production environments set both of these to FALSE and run your migrations manually or as part of an update script.