Rails Migration Cheat Sheet

Make sure you view the (short) screencast by DHH

VERIFY: To enable full use of ruby schema support, uncomment ‘config.active_record.schema_format = :ruby’ in your /config/environment. (Update: The rails schema mechanism is the default as of Rails 1.1)

• rake db_schema_dump: run after you create a model to capture the schema.rb
• rake db_schema_import: import the schema file into the current database (on error, check if your schema.rb has ”:force => true” on the create table statements
• ./script/generate migration MigrationName: generate a new migration with a new ‘highest’ version (run ’./script/generate migration’ for this info at your fingertips)
• rake migrate: migrate your current database to the most recent version
• rake migrate VERSION=5: migrate your current database to a specific version (in this case, version 5)

(run rake -T for most of this information as rake usage information)

Example schema.rb:

ActiveRecord::Schema.define(:version => 2) do

  create_table "comments", :force => true do |t|
    t.column "body", :text
    t.column "post_id", :integer
  end

  create_table "posts", :force => true do |t|
    t.column "title", :string
    t.column "body", :text
    t.column "created_at", :datetime
    t.column "author_name", :string
    t.column "comments_count", :integer, :default => 0
  end

end

What can I do?

• 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)

See the Rails API for details on these.

Example migration:

class UpdateUsersAndCreateProducts < ActiveRecord::Migration
  def self.up
    rename_column "users", "password", "hashed_password" 
    remove_column "users", "email" 

    create_table "products", :force => true do |t|
        t.column "name", :text
        t.column "description", :text
    end
  end

  def self.down
    rename_column "users", "hashed_password", "password" 
    add_column "users", "email" 
    drop_table "products" 
  end
end

Executing SQL directly

• execute “ALTER TABLE `pages_linked_pages` ADD UNIQUE `page_id_linked_page_id` (`page_id`,`linked_page_id`)”

Remember to be cautious of DB specific SQL!

Problems? When the migration fails

ruby script/runner 'ActiveRecord::Base.connection.execute( 
"INSERT INTO schema_info (version) VALUES(0)")'

• Thanks to the Chad Fowler’s new Rails Recipes book for this one. Note that (duh) you can run any sql like this.

Snippets

On OS X, I’m using TextMate with the syncPEOPLE on Rails v.0.9
TextMate Bundle. This provides the following…
(snipped from the release notes)

Snippets are small capsules of code that are activated by a key sequence followed by the [tab] key. For example, mcdt[tab] will activate the Migration Create and Drop Table snippet.

• mcdt: Migration Create and Drop Table
• mcc: Migration Create Column
• marc: Migration Add and Remove Column
• mct: Migration Create Table
• mdt: Migration Drop Table
• mac: Migration Add Column
• mrc: Migration Remove Column

See Also Sami Samhuri’s information for a more complete description of these snippets

Additional places to look:

• Steve Eichert: Migrations Explained
• The RailsConf 2006 Agile Databases with Migrations Presentation Slides by Damon Clinkscales has a great deal of useful information as well.