In my previous post on migrations i wrote that “…they are not covered in any of the basic books on RoR”. Well, this statement does not hold anymore, since Agile Web Development with Rails, 2nd ed. is already creating the models with migrations.

While the last part of the post (why are migrations so cool) is still up-to-date, they way of creating migrations is different from 1.1 on, so i have decided to review the topic and add some new points, too.

Migrations are now created automatically with the model

In my previous post, i have been creating the migration manually with the command

ruby script/generate migration ProductMigration

However, as of Rails 1.1, you don’t have to do this anymore. When you generate the model (let’s stick with the Product model as an example) the migration is automatically generated:

ruby script/generate model Product
...
... #some lines omited
...
create db/migrate/001_create_products.rb

Now you can edit the file db/migrate/001_create_products.rb to contain something like this:

class ProductMigration < ActiveRecord::Migration
def self.up
create_table :products do |table|
table.column :title,       :string
table.column :description, :text
table.column :image_url,   :string end
(rest of the file omited)

Then run

rake db:migrate

To update the database. That's even easier than in the previous versions of rails!

Valid column data types and possible options

Valid columns are:

integer, float, datetime, date, timestamp, time, text, string, binary and boolean.

Valid column options:

• limit ( :limit => “50” )
• default (:default => “blah” )
• null (:null => false implies NOT NULL)

string is the equivalent of varchar(255), so if you would like to have a string column (called title) of length 100 instead of 255, with default value 'Some title' and to forbid NULL value, you have to type

table.column :title,
:string,
:limit   => 100,
:default => "Some title",
:null    => false

Generating test data

I am quite sure you know the situation when you want to test something quickly and you waste precious time to generate some test data, which you trash after the testing just to find yourself in the same situation later?

Well, migrations can help you to prevent headaches because of this, too. Here is how:

ruby script/generate migration create_test_data
Create db/migrate/002_create_test_data.rb

You can create test data inside the migration file like this:

class ProductMigration < ActiveRecord::Migration
def self.up
Product.create(:title => 'My cool book about the meaning of life',
:description => '42',
:image_url => /images/cool_book42.png)

You can now commit this migration to the RCS you are using, and modify/add more test data later.

The other advantage is that your colleagues won't spend time writing dummy test data either: they can just check out this migration and happily use the provided tests.

If this is still not enough for you...

You can write SQL statements inside the migrations. For example:

execute "alter table items
add constraint fk_items_products
foreign key (product_id) references products(id)"

However, use this with care since you have to write native DDL statements, which violates one of the fundamental 'cool factors' of migrations: independence from DB vendors.

Conclusion

The Agile Web Development with Rails, 2nd ed can be considered as the Rails bible and since it is promoting migrations as the definitive way to handle your DB issues, i think migrations will become (in fact the already did for lots of people) the state of the art. After using them for a while and enjoying the power and flexibility they provide without having significant drawbacks, i don't really see why should one not use them in the future.

Although migrations are a very cool feature of Ruby on Rails, they are not covered in any of the basic books on RoR i have encountered so far (Agile Web Development with Rails, Ruby for Rails Programmers).

Update: Check out my recent post: Ruby on Rails Migrations: Reloaded for an update.

Both these books are using an ‘in medias res’ style approach – they guide the reader through the essential features of Rails by building a web app from scratch. The models in the examples are creaed in SQL rather than with migrations. Let’s examine the difference on a simple example, taken from AWDwR. (Further I am assuming that you have generated a rails application, a development database for the application and the DB connection settings (database.yaml) are correct.)

The classic way: SQL DDL

Create the sql file, create.sql:

drop table if exists products;
create table products (
id           int            not null auto_increment,
title        varchar(100)   not null,
description  text           not null,
image_url    varchar(200)   not null,
price        decimal(10,2)  not null,
primary key (id)
);

After this, you can create the table with:

mysql name_of_your_DB < create.sql

You are now ready to generate your model.

Doing the same with migrations

In your rails app directory, issue the following command:

ruby script/generate migration ProductMigration

then open the file db/migrate/001_product_migration.rb and edit it. To achieve the same result as in the SQL example, the file should look like this:

class ProductMigration < ActiveRecord::Migration

def self.up create_table :products do |table|

table.column :title,
:string,
:limit => 100,
:null => false

table.column :description,
:text,
:null => false

table.column :image_url,
:string,
:limit => 200,
:null => false

table.column :price,
:float,
:null => false
end
end

def self.down
drop_table :products
end
end

Run the migration wit the following command:

rake migrate [VERSION=version_number]

And you achieved the same result as with the first method!

That's very nice, but...

Well, if the only purpose of migrations would be solely the possibility to write Ruby code instead of SQL, even this would be enough for me to go for them. However, i have to admit that this alone would be a rather feeble argument. The good news is that it is not! There is much more to migrations than writing Ruby code:

• Migrations are DB agnostic - The 'write once, use everywhere' principle really works here!
• You don't have to think about obscure SQL specific things anymore - let Rails handle them for you! (OK there are some really complicated things, but fortunately they are adressed by some great books like Rails Recipes, code snippets like Migrate Plus, and I believe that by the Rails team, too.)
• You can change the database as much as you want, and the data you have already there is not affected.
• You get very effective versioning: track changes, concurrent versions, upgrade/downgrade your schemas easily!
• You can generate DB schemas from migrations.
• And possibly much much more... I am a newbie too! 😉

In my oppinion, judging based on the Rails mailing list discussions, migrations are accepted more and more as the definitve way of creating, maintaining, versioning your DB models - so everybody considering serious Rails development should give them a look!