1 files changed, 159 insertions, 0 deletions
diff --git a/railties/doc/guides/migrations/writing_a_migration.txt b/railties/doc/guides/migrations/writing_a_migration.txt
new file mode 100644
index 0000000000..a8c1a78e07
--- /dev/null
+++ b/railties/doc/guides/migrations/writing_a_migration.txt
@@ -0,0 +1,159 @@
+== 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 ActiveRecord 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 ActiveRecord 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 ===
+
+ActiveRecord 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. ActiveRecord 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 :attachement, :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 ActiveRecord 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.
+