Complete Examples

Some complete examples

Complete Example (A)

Create a few migrations, which create a set of tables and modify some existing data.

    php main.php db:generate create_users_table

    php main.php db:generate create_posts_table

    php main.php db:generate fix_dangling_phones_data_bug

    php main.php db:generate add_deleted_at_column_to_posts_table

Assuming these were the first migrations in the system, the above commands would create files like:

    db/migrate/20100909133617_CreateUsersTable.php
    db/migrate/20100909133814_CreatePostsTable.php
    db/migrate/20100909133840_FixDanglingPhonesDataBug.php
    db/migrate/20100909133987_AddDeletedAtColumnToPostsTable.php

Contents of db/migrate/20100909133617_CreateUsersTable.php:

    <?php

    class CreateUsersTable extends Ruckusing_BaseMigration {

      public function up() {
        $t = $this->create_table("users", array("id" => false));
        $t->column("user_id", "integer", array("primary_key"      => true, 
                                               "auto_increment"   => true, 
                                               "unsigned"         => true, 
                                               "null"             => false));
        $t->column("first_name", "string");
        $t->column("last_name", "string");
        $t->column("email", "string", array("limit" => 128));
        $t->column("title", "string");
        $t->finish();
		
        $this->add_index("users", "email", array("unique" => true));
      }//up()

      public function down() {
        $this->drop_table("users");
      }//down()
    }
    ?>

The contents of db/migrate/20100909133814_CreatePostsTable.php might be the following.

Note: We're going to create a two-column primary key.

    <?php

    class CreatePostsTable extends Ruckusing_BaseMigration {

      public function up() {
        $t = $this->create_table("posts", array("id" => false));
        $t->column("post_id", "integer", array("null" => false, "primary_key" => true));
        $t->column("subject", "string");
        $t->column("body", "string");
        $t->column("created_at", "datetime", array('null' => false, "primary_key" => true));
        $t->column("author_id", "integer");
        $t->finish();
		
        $this->add_index("posts", "author_id");
      }//up()
  
      public function down() {
        $this->drop_table("posts");
      }//down()
    }
    ?>

The contents of db/migrate/20100909133840_FixDanglingPhonesDataBug.php might be:

    <?php

    class FixDanglingPhonesDataBug extends Ruckusing_BaseMigration {

      public function up() {
        $this->execute("UPDATE phones SET area_code = '415' WHERE area_code IS NULL");
      }//up()

      public function down() {
         //Nothing to do. Data was wrong due to bug (#3461), so lets just fix
         // it once and for all.
      }//down()
    }
    ?>

The contents of db/migrate/20100909133987_AddDeletedAtColumnToPostsTable.php might be:

    <?php

    class AddDeletedAtColumnToPostsTable extends Ruckusing_BaseMigration {

      public function up() {
        $this->add_column("posts", "deleted_at", "datetime");
      }//up()

      public function down() {
        $this->remove_column("posts", "deleted_at");
      }//down()
    }
    ?>

Finally, lets execute the above migrations:

    php main.php db:migrate

    Started: 2010-09-03 9:26pm PDT

    [db:migrate]: 
            Migrating UP to: 4 (current version: 0)
    ========= CreateUsersTable ======== (0.11)
    ========= CreatePostsTable ======== (0.00)
    ========= FixDanglingPhonesDataBug ======== (0.00)
    ========= AddDeletedAtColumnToPostsTable ======== (0.00)


    Finished: 2010-09-03 9:26pm PDT

Summary

For every migration it is important to also implement the down() method which just undos what was done in the up() method. Of course, not all migrations have appropriate logic to be performed when going down(), in which cases one should just document the reasons.