vendor/rails/railties/doc/guides/source/migrations/writing_a_migration.txt

   1 == Writing a Migration ==
   2
   3 Once you have created your migration using one of the generators it's time to get to work!
   4
   5 === Creating a table ===
   6
   7 `create_table` will be one of your workhorses. A typical use would be
   8
   9 [source, ruby]
  10 ---------------------
  11 create_table :products do |t|
  12   t.string :name
  13 end
  14 ---------------------
  15 which creates a `products` table with a column called `name` (and as discussed below, an implicit `id` column).
  16
  17 The object yielded to the block allows you create columns on the table. There are two ways of doing this. The first looks like
  18
  19 [source, ruby]
  20 ---------------------
  21 create_table :products do |t|
  22   t.column :name, :string, :null => false
  23 end
  24 ---------------------
  25
  26 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.
  27
  28 [source, ruby]
  29 ---------------------
  30 create_table :products do |t|
  31   t.string :name, :null => false
  32 end
  33 ---------------------
  34
  35 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
  36
  37 [source, ruby]
  38 ---------------------
  39 create_table :products, :options => "ENGINE=BLACKHOLE" do |t|
  40   t.string :name, :null => false
  41 end
  42 ---------------------
  43 Will append `ENGINE=BLACKHOLE` to the sql used to create the table (when using MySQL the default is "ENGINE=InnoDB").
  44
  45 The types Active Record supports are `:primary_key`, `:string`, `:text`, `:integer`, `:float`, `:decimal`, `:datetime`, `:timestamp`, `:time`, `:date`, `:binary`, `:boolean`.
  46
  47 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
  48 types not supported by Active Record when using the non sexy syntax, for example
  49
  50 [source, ruby]
  51 ---------------------
  52 create_table :products do |t|
  53   t.column :name, 'polygon', :null => false
  54 end
  55 ---------------------
  56 This may however hinder portability to other databases.
  57
  58 === Changing tables ===
  59
  60 `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
  61
  62 [source, ruby]
  63 ---------------------
  64 change_table :products do |t|
  65   t.remove :description, :name
  66   t.string :part_number
  67   t.index :part_number
  68   t.rename :upccode, :upc_code
  69 end
  70 ---------------------
  71 removes the `description` column, creates a `part_number` column and adds an index on it. Finally it renames the `upccode` column.   This is the same as doing
  72
  73 [source, ruby]
  74 ---------------------
  75 remove_column :products, :description
  76 remove_column :products, :name
  77 add_column :products, :part_number, :string
  78 add_index :products, :part_number
  79 rename_column :products, :upccode, :upc_code
  80 ---------------------
  81
  82 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`.
  83
  84 === Special helpers ===
  85
  86 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:
  87
  88 [source, ruby]
  89 ---------------------
  90 create_table :products do |t|
  91   t.timestamps
  92 end
  93 ---------------------
  94 will create a new products table with those two columns whereas
  95
  96 [source, ruby]
  97 ---------------------
  98 change_table :products do |t|
  99   t.timestamps
 100 end
 101 ---------------------
 102 adds those columns to an existing table.
 103
 104 The other helper is called `references` (also available as `belongs_to`). In its simplest form it just adds some readability
 105
 106 [source, ruby]
 107 ---------------------
 108 create_table :products do |t|
 109   t.references :category
 110 end
 111 ---------------------
 112
 113 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:
 114
 115 [source, ruby]
 116 ---------------------
 117 create_table :products do |t|
 118   t.references :attachment, :polymorphic => {:default => 'Photo'}
 119 end
 120 ---------------------
 121 will add an `attachment_id` column and a string `attachment_type` column with a default value of 'Photo'.
 122
 123 NOTE: The `references` helper does not actually create foreign key constraints for you. You will need to use `execute` for that or a plugin that adds <<foreign_key,foreign key support>>.
 124
 125 If the helpers provided by Active Record aren't enough you can use the `execute` function to execute arbitrary SQL.
 126
 127 For more details and examples of individual methods check the API documentation, in particular the documentation for http://api.rubyonrails.com/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html[ActiveRecord::ConnectionAdapters::SchemaStatements] (which provides the methods available in the `up` and `down` methods),  http://api.rubyonrails.com/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html[ActiveRecord::ConnectionAdapters::TableDefinition] (which provides the methods available on the object yielded by `create_table`) and http://api.rubyonrails.com/classes/ActiveRecord/ConnectionAdapters/Table.html[ActiveRecord::ConnectionAdapters::Table] (which provides the methods available on the object yielded by `change_table`).
 128
 129 === Writing your down method ===
 130
 131 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 `up` method. For example
 132
 133 [source, ruby]
 134 ---------------------
 135 class ExampleMigration < ActiveRecord::Migration
 136
 137   def self.up
 138     create_table :products do |t|
 139       t.references :category
 140     end
 141     #add a foreign key
 142     execute "ALTER TABLE products ADD CONSTRAINT fk_products_categories FOREIGN KEY (category_id) REFERENCES categories(id)"
 143
 144     add_column :users, :home_page_url, :string
 145
 146     rename_column :users, :email, :email_address
 147   end
 148
 149   def self.down
 150     rename_column :users, :email_address, :email
 151     remove_column :users, :home_page_url
 152     execute "ALTER TABLE products DROP FOREIGN KEY fk_products_categories"
 153     drop_table :products
 154   end
 155 end
 156 ---------------------
 157 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
 158 displayed saying that it can't be done.
 159