Rails migrations are brilliant. I say this because until now I had heard of them, seen articles about them and like poor misguided VB programmers I had completely ignored them. They make loads of potentially tricky database migration, rollback and versioning issues a doddle but mainly (from my point of view) they mean I can develop more in ruby and less in SQL. This makes my development faster, easier and more standardised which in turn makes my life simpler, calmer and more fun – everybody wins.

Honestly they do.

Step 1 – Create a rails project

I am assuming you know how to do this – if not you probably wouldn’t be reading this but try reading this.

Step 2 – Export your existing schema

We have reached step 2 and you probably haven’t had to think yet – good sign. Simply run the following script (from in your apps directory)

rake db:schema:dump

This will create a new file in the db folder called schema.rb which will be a simple ruby class for creating your database. If you are working with a new database it will just be a skeleton class, but for an existing database it will have been filled-up with lovely looking ruby code to create the database as it currently stands.

Step 3 – Wait for the inevitable change in requirements

If your new requirements need a database schema change then this is where migrations come in useful. Each new version of your database will be built by running the schema.rb file followed by each of a set of sequentially numbered migration classes. This is easier than it sounds, simply run the following command to create your next version.

script/generate migration new_version_name

the new_version_name can be changed to describe what you intent to do with the next version. This will generate a file in the db/migrate folder prefixed with the sequential version number of the change. In this case 001_new_version_name.rb has been created, the content of which should look like this…

class NewVersionName < ActiveRecord::Migration

def self.up
  # add your code to upgrade the current
  # version of the database to this version
end

def self.down
  # add your code to downgrade the next
  # version of the database to this version
end

end

Step 4 – Make your schema changes

For the purposes of this example I’m going add a new table to the database, this involves adding code to the self.up and self.down methods.

class NewVersionName < ActiveRecord::Migration

def self.up

  create_table "subscriptions", :force => true do |t|
    t.column "name",        :string,   :default => "", :null => false
    t.column "max_users",   :integer,  :limit => 10,   :null => false
    t.column "created",     :datetime,                 :null => false
    t.column "payed_until", :date,                     :null => false
  end

  add_index "subscriptions", ["name"], :name => "unique_name", :unique => true

end

def self.down
  drop_index :subscriptions, :unique_name
  drop_table :subscriptions
end

end

The simple example above needs very little explanation to anyone familiar with ruby,

essentially we add code to migrate up to and down to this version of the schema from the previous and next versions respectively. The following options are availible…

create_table(name, options)
    drop_table(name)
    rename_table(old_name, new_name)
    add_column(table_name, column_name, type, options)
    rename_column(table_name, column_name, new_column_name)
    change_column(table_name, column_name, type, options)
    remove_column(table_name, column_name)
    add_index(table_name, column_name, index_type)
    remove_index(table_name, column_name)

Step 5 – Upgrade the database to your new version

Running the following command executes all new migration classes (in this case just the one) that have not been previously run against the database.

rake db:migrate

It is often useful to add the -t option to see any errors in detail. You can also specify a particular version by adding the VERSION=x option. This uses the self.up and self.down code to rollback or forward to the specified version.

That’s it – easy isn’t it. For more detailed information try the

rails wiki page.