soaked and soaped

written September 5 2006 by

Kommen

tagged with

Development, Howto, Migrations, Rails

8 Comments so far. Go, post one!

Previous Building a herbal bed

State of Web Development 2006 Next

Related Articles

Exception Notifier - Ruby on Rails plugin

State of Web Development 2006

Install Mongrel on Ubuntu 6.06 Dapper

Parse natural language date/time strings in Ruby with Chronic

This is all about how to use Migrations in Ruby on rails to make your work even more productive.

I’m developing with Ruby on Rails since 8 month now, coming from Java and PHP.
But only a few days ago I discovered one powerful feature of Ruby on Rails: Migrations.

I think there are a lot of others (like I was) who develop with Rails, but don’t know how to use migrations and how helpful they are.

For those, here is a litte introduction.

h3. The Basics

What are migrations?

With migrations you

• define your database schema in Ruby code.
• make your database schema portable to various databases (MySQL, PostgreSQL, SQLite, MS SQL Server and Oracle).
• make it easier for development teams to distribute changes in the database schema.
• can see how your database schema developed while your application grew up.
• can synchronize your application code with your database schema (if you are using a version control system like subversion).

Using them…

In general there are 3 steps to use migrations (e.g. creating a table for your authentication system):

1. Create a migration file. Therefore you can use the script/generate migration script.

ruby script/generate migration create_users_table
</pre>

This will generate a file _xxx_create_users_table.rb_ in the db/migrations folder, where xxx is a version number.

2. Write your migration code. The file can look like this:
Example 1: How a basic migration might look like written in code.

  
 1 class CreateUsersTable < ActiveRecord::Migration
 2   def self.up
 3     create_table "users" do |t|
 4       t.column "name", :string, :default => "", :null => false
 5       t.column "login", :string, :limit => 80
 6       t.column "password", :string, :limit => 40
 7       t.column "email", :string, :limit => 100, :default => "", :null => false
 8     end 
 9   end
10 
11   def self.down
12     drop_table :users
13   end
14 end



Short explenation:

The self.up method is called when you “roll up” your database. In this example it will create a table users with 4 columns: name, login, _password, and email.

The self.up method is called when you “roll back” your database to a previous version. In this case the table users will be removed.


3. Migrate! I your application root directory runs


rake migrate
</pre>

This command will check your current database version (therefore the schema_info table exists!) and then perform all needed migrations to get your database up to date.

Of course you can do more
Here are 2 more code examples that are (more or less) self-explaining:
Example class 1: AddCommentTextToAddresses

  
 1 class AddCommentTextToAddresses < ActiveRecord::Migration
 2   def self.up
 3     add_column :addresses, :comment_text, :text, :default => "", :null => false
 4   end
 5 
 6   def self.down
 7     remove_column :addresses, :comment_text
 8   end
 9 end


Example class 2: AddDefaultTags

  
 1 class AddDefaultTags < ActiveRecord::Migration
 2   @tags = %w(Friend Buddy Enemy)
 3   
 4   def self.up
 5     @tags.each {|t| Tag.create :name => t }
 6   end
 7 
 8   def self.down
 9     @tags.each {|t| Tag.find_by_name(t).destroy }
10   end
11 end


Hints
It’s possible to build your migrations from any existing database also if you haven’t used migrations before.

Typing all of your existing database schema in ruby code is a pain, but you can cheat a bit:

Run rake db:schema:dump. This will generate a schema.rb in your db/ directory. From there

you can copy most of the ruby code for creating your migrations.
Note that when you create a new model with script/generate model ModelName a migration file is automatically created for you. You just have to type your code into the generated template. (Thanks to ryanb for that)
Conclusion
Just give migrations a try… and you’ll love them!
Sources
for further reading:

	
Understanding Migrations
	
Migrations API Doc
	
Using Migrations

posted in the hope to get more Rails developers using migrations