writing_a_migration.txt

== Writing a Migration ==

Once you have created your migration using one of the generators it's time to get to work!

=== Creating a table ===

`create_table` will be one of your workhorses. A typical use would be

[source, ruby]
---------------------
create_table :products do |t|
  t.string :name
end
---------------------
which creates a products table with a column called name (and as discussed below, an implicit id column).

The object yielded to the block allows you create columns on the table. There are two ways of the doing this. The first looks like

[source, ruby]
---------------------
create_table :products do |t|
  t.column :name, :string, :null => false
end
---------------------

the second form, the so called "sexy" migrations, drops the somewhat redundant column method. Instead, the `string`, `integer` etc. methods create a column of that type. Subsequent parameters are identical.

[source, ruby]
---------------------
create_table :products do |t|
  t.string :name, :null => false
end
---------------------

By default `create_table` will create a primary key called `id`. You can change the name of the primary key with the `:primary_key` option (don't forget to update the corresponding model) or if you don't want a primary key at all (for example for a HABTM join table) you can pass `:id => false`. If you need to pass database specific options you can place an sql fragment in the `:options` option. For example

[source, ruby]
---------------------
create_table :products, :options => "ENGINE=InnoDB" do |t|
  t.string :name, :null => false
end
---------------------
Will append `ENGINE=InnoDB` to the sql used to create the table.

The types Active Record supports are `:primary_key`, `:string`, `:text`, `:integer`, `:float`, `:decimal`, `:datetime`, `:timestamp`, `:time`, `:date`, `:binary`, `:boolean`.

These will be mapped onto an appropriate underlying database type, for example with MySQL `:string` is mapped to `VARCHAR(255)`. You can create columns of 
types not supported by Active Record when using the non sexy syntax, for example

[source, ruby]
---------------------
create_table :products do |t|
  t.column :name, 'polygon', :null => false
end
---------------------
This may however hinder portability to other databases.

=== Changing tables ===

`create_table`'s close cousin is `change_table`. Used for changing existing tables, it is used in a similar fashion to `create_table` but the object yielded to the block knows more tricks. For example

[source, ruby]
---------------------
change_table :products do |t|
  t.remove :description, :name
  t.string :part_number
  t.index :part_number
  t.rename :upccode, :upc_code
end
---------------------
removes the description column, creates a part_number column and adds an index on it. This is the same as doing

[source, ruby]
---------------------
remove_column :products, :description
remove_column :products, :name
add_column :products, :part_number, :string
add_index :products, :part_number
rename_column :products, :upccode, :upc_code
---------------------

You don't have to keep repeating the table name and it groups all the statements related to modifying one particular table. The individual transformation names are also shorter, for example `remove_column` becomes just `remove` and `add_index` becomes just `index`.

=== Special helpers ===

Active Record provides some shortcuts for common functionality. It is for example very common to add both the `created_at` and `updated_at` columns and so there is a method that does exactly that:

[source, ruby]
---------------------
create_table :products do |t|
  t.timestamps
end
---------------------
will create a new products table with those two columns whereas

[source, ruby]
---------------------
change_table :products do |t|
  t.timestamps
end
---------------------
adds those columns to an existing table.

The other helper is called `references` (also available as `belongs_to`). In its simplest form it just adds some readability

[source, ruby]
---------------------
create_table :products do |t|
  t.references :category
end
---------------------

will create a `category_id` column of the appropriate type. Note that you pass the model name, not the column name. Active Record adds the `_id` for you. If you have polymorphic belongs_to associations then `references` will add both of the columns required:

[source, ruby]
---------------------
create_table :products do |t|
  t.references :attachment, :polymorphic => {:default => 'Photo'}
end
---------------------
will add an `attachment_id` column and a string `attachment_type` column with a default value of 'Photo'.

NOTE: The `references` helper does not actually create foreign key constraints for you. You will need to use execute for that.

If the helpers provided by Active Record aren't enough you can use the `execute` function to execute arbitrary SQL.

For more details and examples of individual methods check the API documentation.

=== Writing your down method ===

The `down` method of your migration should revert the transformations done by the up method. In other words the database should be unchanged if you do an up followed by a down. For example if you create a table in the up you should drop it in the down method. It is wise to do things in precisely the reverse order to in the the up method. For example

[source, ruby]
---------------------
class ExampleMigration < ActiveRecord::Migration

  def self.up
    create_table :products do |t|
      t.references :category
    end
    #add a foreign key
    execute "ALTER TABLE products ADD CONSTRAINT fk_products_categories FOREIGN KEY (category_id) REFERENCES categories(id)"
    
    add_column :users, :home_page_url, :string
    
    rename_column :users, :email, :email_address
  end
  
  def self.down
    rename_column :users, :email_address, :email
    remove_column :users, :home_page_url
    execute "ALTER TABLE products DROP FOREIGN KEY fk_products_categories"
    drop_table :products
  end
end
---------------------
Sometimes your migration will do something which is just plain irreversible, for example it might destroy some data. In cases like those when you can't reverse the migration you can raise `IrreversibleMigration` from your down method. If someone tries to revert your migration an error message will be
displayed saying that it can't be done.