diff options
| -rw-r--r-- | railties/guides/source/association_basics.textile | 31 | ||||
| -rw-r--r-- | railties/guides/source/getting_started.textile | 15 | ||||
| -rw-r--r-- | railties/guides/source/migrations.textile | 76 |
3 files changed, 48 insertions, 74 deletions
diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index e5b8c73c43..94dce1b97b 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -229,7 +229,7 @@ The corresponding migration might look like this: <ruby> class CreateSuppliers < ActiveRecord::Migration - def self.up + def change create_table :suppliers do |t| t.string :name t.timestamps @@ -241,11 +241,6 @@ class CreateSuppliers < ActiveRecord::Migration t.timestamps end end - - def self.down - drop_table :accounts - drop_table :suppliers - end end </ruby> @@ -314,7 +309,7 @@ If you have an instance of the +Picture+ model, you can get to its parent via +@ <ruby> class CreatePictures < ActiveRecord::Migration - def self.up + def change create_table :pictures do |t| t.string :name t.integer :imageable_id @@ -322,10 +317,6 @@ class CreatePictures < ActiveRecord::Migration t.timestamps end end - - def self.down - drop_table :pictures - end end </ruby> @@ -333,17 +324,13 @@ This migration can be simplified by using the +t.references+ form: <ruby> class CreatePictures < ActiveRecord::Migration - def self.up + def change create_table :pictures do |t| t.string :name t.references :imageable, :polymorphic => true t.timestamps end end - - def self.down - drop_table :pictures - end end </ruby> @@ -413,17 +400,13 @@ This declaration needs to be backed up by the proper foreign key declaration on <ruby> class CreateOrders < ActiveRecord::Migration - def self.up + def change create_table :orders do |t| t.datetime :order_date t.string :order_number t.integer :customer_id end end - - def self.down - drop_table :orders - end end </ruby> @@ -451,16 +434,12 @@ These need to be backed up by a migration to create the +assemblies_parts+ table <ruby> class CreateAssemblyPartJoinTable < ActiveRecord::Migration - def self.up + def change create_table :assemblies_parts, :id => false do |t| t.integer :assembly_id t.integer :part_id end end - - def self.down - drop_table :assemblies_parts - end end </ruby> diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 366df9cd84..63bb38318c 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -378,7 +378,7 @@ If you look in the +db/migrate/20100207214725_create_posts.rb+ file (remember, y <ruby> class CreatePosts < ActiveRecord::Migration - def self.up + def change create_table :posts do |t| t.string :name t.string :title @@ -387,14 +387,10 @@ class CreatePosts < ActiveRecord::Migration t.timestamps end end - - def self.down - drop_table :posts - end end </ruby> -The above migration creates two methods, +up+, called when you run this migration into the database, and +down+ in case you need to reverse the changes made by this migration at a later date. The +up+ command in this case creates a +posts+ table with two string columns and a text column. It also creates two timestamp fields to track record creation and updating. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide. +The above migration creates a method name +change+ which will be called when you run this migration. The action defined in that method is also reversible, which means Rails knows how to reverse the change made by this migration, in case you want to reverse it at later date. By default, when you run this migration it will creates a +posts+ table with two string columns and a text column. It also creates two timestamp fields to track record creation and updating. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide. At this point, you can use a rake command to run the migration: @@ -807,7 +803,7 @@ In addition to the model, Rails has also made a migration to create the correspo <ruby> class CreateComments < ActiveRecord::Migration - def self.up + def change create_table :comments do |t| t.string :commenter t.text :body @@ -818,10 +814,6 @@ class CreateComments < ActiveRecord::Migration add_index :comments, :post_id end - - def self.down - drop_table :comments - end end </ruby> @@ -1458,6 +1450,7 @@ Two very common sources of data that are not UTF-8: h3. Changelog +* April 26, 2011: Changed migration code from +self.up+, +self.down+ pair to +change+ method "Prem Sichanugrist":"http://sikachu.com" * April 11, 2011: Changed scaffold_controller generator to create format block for JSON instead of XML "Sebastian Martinez":http://www.wyeworks.com * August 30, 2010: Minor editing after Rails 3 release by "Joost Baaij":http://www.spacebabies.nl * July 12, 2010: Fixes, editing and updating of code samples by "Jaime Iniesta":http://jaimeiniesta.com diff --git a/railties/guides/source/migrations.textile b/railties/guides/source/migrations.textile index bf5d4d3e4d..238fe3603b 100644 --- a/railties/guides/source/migrations.textile +++ b/railties/guides/source/migrations.textile @@ -58,6 +58,23 @@ end This migration adds a +receive_newsletter+ column to the +users+ table. We want it to default to +false+ for new users, but existing users are considered to have already opted in, so we use the User model to set the flag to +true+ for existing users. +Also, you might also found a smart migration file, which was introduced in the latest version of Rails: + +<ruby> +class CreateProducts < ActiveRecord::Migration + def change + create_table :products do |t| + t.string :name + t.text :description + + t.timestamps + end + end +end +</ruby> + +This smart migration file knows how to migrate your database and reverse it in case you needed. It's more preferrable way to write a constructive (i.e. add column or add table) migration file. + NOTE: Some "caveats":#using-models-in-your-migrations apply to using models in your migrations. h4. Migrations are Classes @@ -116,7 +133,7 @@ will create a migration that looks like this <ruby> class CreateProducts < ActiveRecord::Migration - def self.up + def change create_table :products do |t| t.string :name t.text :description @@ -124,10 +141,6 @@ class CreateProducts < ActiveRecord::Migration t.timestamps end end - - def self.down - drop_table :products - end end </ruby> @@ -146,10 +159,7 @@ This will create an empty but appropriately named migration: <ruby> class AddPartNumberToProducts < ActiveRecord::Migration - def self.up - end - - def self.down + def change end end </ruby> @@ -164,13 +174,9 @@ will generate <ruby> class AddPartNumberToProducts < ActiveRecord::Migration - def self.up + def change add_column :products, :part_number, :string end - - def self.down - remove_column :products, :part_number - end end </ruby> @@ -194,6 +200,8 @@ class RemovePartNumberFromProducts < ActiveRecord::Migration end </ruby> +NOTE: The generated migration file for destructive migration will be created using the old-style migration with +up+ and +down+ method. This because Rails doesn't know the original data type defined when you added the column. + You are not limited to one magically generated column, for example <shell> @@ -204,15 +212,10 @@ generates <ruby> class AddDetailsToProducts < ActiveRecord::Migration - def self.up + def change add_column :products, :part_number, :string add_column :products, :price, :decimal end - - def self.down - remove_column :products, :price - remove_column :products, :part_number - end end </ruby> @@ -337,6 +340,17 @@ If the helpers provided by Active Record aren't enough you can use the +execute+ For more details and examples of individual methods check the API documentation, in particular the documentation for "<tt>ActiveRecord::ConnectionAdapters::SchemaStatements</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html (which provides the methods available in the +up+ and +down+ methods), "<tt>ActiveRecord::ConnectionAdapters::TableDefinition</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html (which provides the methods available on the object yielded by +create_table+) and "<tt>ActiveRecord::ConnectionAdapters::Table</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html (which provides the methods available on the object yielded by +change_table+). +h4. Writing Your +change+ Method + +The +change+ method of your migration reduce the need for you having to write both +up+ and +down+ method in some case that Rails knows how to revert it. Rails will revert the changes automatically when you rollback your change. Currently, +change+ method only support these migration definitions: + +* +create_table+ +* +add_column+ +* +rename_column+ +* +add_index+ + +If you're going to use another methods, you'll have to write both +up+ and +down+ method normally. + h4. Writing Your +down+ Method The +down+ method of your migration should revert the transformations done by the +up+ method. In other words the database schema should be unchanged if you do an +up+ followed by a +down+. For example if you create a table in the +up+ method 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 @@ -369,9 +383,8 @@ class ExampleMigration < ActiveRecord::Migration end end </ruby> -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. +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. h3. Running Migrations @@ -449,7 +462,7 @@ For example, this migration <ruby> class CreateProducts < ActiveRecord::Migration - def self.up + def change suppress_messages do create_table :products do |t| t.string :name @@ -465,10 +478,6 @@ class CreateProducts < ActiveRecord::Migration 250 end end - - def self.down - drop_table :products - end end </ruby> @@ -499,11 +508,7 @@ class AddPartNumberToProducts < ActiveRecord::Migration class Product < ActiveRecord::Base end - def self.up - ... - end - - def self.down + def change ... end end @@ -519,15 +524,11 @@ class AddPartNumberToProducts < ActiveRecord::Migration class Product < ActiveRecord::Base end - def self.up + def change add_column :product, :part_number, :string Product.reset_column_information ... end - - def self.down - ... - end end </ruby> @@ -590,5 +591,6 @@ Although Active Record does not provide any tools for working directly with such h3. Changelog +* April 26, 2011: change generated +up+ and +down+ methods to +change+ method, and describe detail about +change+ method by "Prem Sichanugrist":http://sikachu.com * July 15, 2010: minor typos corrected by "Jaime Iniesta":http://jaimeiniesta.com * September 14, 2008: initial version by "Frederick Cheung":credits.html#fcheung |