aboutsummaryrefslogtreecommitdiffstats
path: root/railties/guides
diff options
context:
space:
mode:
Diffstat (limited to 'railties/guides')
-rw-r--r--railties/guides/source/migrations.textile94
1 files changed, 46 insertions, 48 deletions
diff --git a/railties/guides/source/migrations.textile b/railties/guides/source/migrations.textile
index f458f1bff9..e67be0ae9f 100644
--- a/railties/guides/source/migrations.textile
+++ b/railties/guides/source/migrations.textile
@@ -20,9 +20,9 @@ SQLite3 in development, but MySQL in production.
In this guide, you'll learn all about migrations including:
-* The generators you can use to create them
-* The methods Active Record provides to manipulate your database
-* The Rake tasks that manipulate them
+* The generators you can use to create them
+* The methods Active Record provides to manipulate your database
+* The Rake tasks that manipulate them
* How they relate to +schema.rb+
endprologue.
@@ -35,7 +35,7 @@ sorts of things you can do:
<ruby>
class CreateProducts < ActiveRecord::Migration
def up
- create_table :products do |t|
+ create_table :products do |t|
t.string :name
t.text :description
@@ -62,7 +62,7 @@ bad data in the database or populate new fields:
<ruby>
class AddReceiveNewsletterToUsers < ActiveRecord::Migration
def up
- change_table :users do |t|
+ change_table :users do |t|
t.boolean :receive_newsletter, :default => false
end
User.update_all ["receive_newsletter = ?", true]
@@ -90,7 +90,7 @@ the migration is rolled back without the need to write a separate +down+ method.
<ruby>
class CreateProducts < ActiveRecord::Migration
def change
- create_table :products do |t|
+ create_table :products do |t|
t.string :name
t.text :description
@@ -113,7 +113,7 @@ database independent way (you'll read about them in detail later):
* +add_index+
* +change_column+
* +change_table+
-* +create_table+
+* +create_table+
* +drop_table+
* +remove_column+
* +remove_index+
@@ -134,11 +134,11 @@ the changes that were made by hand.
h4. What's in a Name
-Migrations are stored as files in the +db/migrate+ directory, one for each
-migration class. The name of the file is of the form
-+YYYYMMDDHHMMSS_create_products.rb+, that is to say a UTC timestamp
-identifying the migration followed by an underscore followed by the name
-of the migration. The name of the migration class (CamelCased version)
+Migrations are stored as files in the +db/migrate+ directory, one for each
+migration class. The name of the file is of the form
++YYYYMMDDHHMMSS_create_products.rb+, that is to say a UTC timestamp
+identifying the migration followed by an underscore followed by the name
+of the migration. The name of the migration class (CamelCased version)
should match the latter part of the file name. For example
+20080906120000_create_products.rb+ should define class +CreateProducts+ and
+20080906120001_add_details_to_products.rb+ should define
@@ -150,7 +150,7 @@ Internally Rails only uses the migration's number (the timestamp) to identify
them. Prior to Rails 2.1 the migration number started at 1 and was incremented
each time a migration was generated. With multiple developers it was easy for
these to clash requiring you to rollback migrations and renumber them. With
-Rails 2.1+ this is largely avoided by using the creation time of the migration
+Rails 2.1+ this is largely avoided by using the creation time of the migration
to identify them. You can revert to the old numbering scheme by adding the
following line to +config/application.rb+.
@@ -163,9 +163,8 @@ allows Rails to handle common situations that occur with multiple developers.
For example Alice adds migrations +20080906120000+ and +20080906123000+ and Bob
adds +20080906124500+ and runs it. Alice finishes her changes and checks in her
-migrations and Bob pulls down the latest changes. When Bob runs +rake
-db:migrate+, Rails knows that it has not run Alice's two migrations so it
-executes the +up+ method for each migration.
+migrations and Bob pulls down the latest changes. When Bob runs +rake db:migrate+,
+Rails knows that it has not run Alice's two migrations so it executes the +up+ method for each migration.
Of course this is no substitution for communication within the team. For
example, if Alice's migration removed a table that Bob's migration assumed to
@@ -177,8 +176,7 @@ Occasionally you will make a mistake when writing a migration. If you have
already run the migration then you cannot just edit the migration and run the
migration again: Rails thinks it has already run the migration and so will do
nothing when you run +rake db:migrate+. You must rollback the migration (for
-example with +rake db:rollback+), edit your migration and then run +rake
-db:migrate+ to run the corrected version.
+example with +rake db:rollback+), edit your migration and then run +rake db:migrate+ to run the corrected version.
In general editing existing migrations is not a good idea: you will be creating
extra work for yourself and your co-workers and cause major headaches if the
@@ -246,9 +244,9 @@ class CreateProducts < ActiveRecord::Migration
end
</ruby>
-You can append as many column name/type pairs as you want. By default, the
-generated migration will include +t.timestamps+ (which creates the
-+updated_at+ and +created_at+ columns that are automatically populated
+You can append as many column name/type pairs as you want. By default, the
+generated migration will include +t.timestamps+ (which creates the
++updated_at+ and +created_at+ columns that are automatically populated
by Active Record).
h4. Creating a Standalone Migration
@@ -256,7 +254,7 @@ h4. Creating a Standalone Migration
If you are creating migrations for other purposes (for example to add a column
to an existing table) then you can also use the migration generator:
-<shell>
+<shell>
$ rails generate migration AddPartNumberToProducts
</shell>
@@ -325,8 +323,8 @@ end
</ruby>
As always, what has been generated for you is just a starting point. You can add
-or remove from it as you see fit by editing the
-db/migrate/YYMMDDHHMMSS_add_details_to_products.rb file.
+or remove from it as you see fit by editing the
+db/migrate/YYYYMMDDHHMMSS_add_details_to_products.rb file.
NOTE: The generated migration file for destructive migrations will still be
old-style using the +up+ and +down+ methods. This is because Rails needs to know
@@ -374,7 +372,7 @@ 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 the option +:id => false+. If you
-need to pass database specific options you can place a SQL fragment in the
+need to pass database specific options you can place an SQL fragment in the
+:options+ option. For example,
<ruby>
@@ -401,8 +399,8 @@ change_table :products do |t|
end
</ruby>
-removes the +description+ and +name+ columns, creates a +part_number+ string
-column and adds an index on it. Finally it renames the +upccode+ column.
+removes the +description+ and +name+ columns, creates a +part_number+ string
+column and adds an index on it. Finally it renames the +upccode+ column.
h4. Special Helpers
@@ -427,7 +425,7 @@ end
adds those columns to an existing table.
Another helper is called +references+ (also available as +belongs_to+). In its
-simplest form it just adds some readability
+simplest form it just adds some readability.
<ruby>
create_table :products do |t|
@@ -446,7 +444,7 @@ create_table :products do |t|
end
</ruby>
-will add an +attachment_id+ column and a string +attachment_type+ column with
+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
@@ -481,8 +479,8 @@ the +change+ method supports only these migration definitions:
* +rename_index+
* +rename_table+
-If you're going to need to use any other methods, you'll have to write the
-+up+ and +down+ methods instead of using the change method.
+If you're going to need to use any other methods, you'll have to write the
++up+ and +down+ methods instead of using the +change+ method.
h4. Using the +up+/+down+ Methods
@@ -531,9 +529,9 @@ can't be done.
h3. Running Migrations
Rails provides a set of rake tasks to work with migrations which boil down to
-running certain sets of migrations.
+running certain sets of migrations.
-The very first migration related rake task you will use will probably be
+The very first migration related rake task you will use will probably be
+rake db:migrate+. In its most basic form it just runs the +up+ or +change+
method for all the migrations that have not yet been run. If there are
no such migrations, it exits. It will run these migrations in order based
@@ -543,8 +541,8 @@ Note that running the +db:migrate+ also invokes the +db:schema:dump+ task, which
will update your db/schema.rb file to match the structure of your database.
If you specify a target version, Active Record will run the required migrations
-(up or down or change) until it has reached the specified version. The version
-is the numerical prefix on the migration's filename. For example, to migrate
+(up or down or change) until it has reached the specified version. The version
+is the numerical prefix on the migration's filename. For example, to migrate
to version 20080906120000 run
<shell>
@@ -553,8 +551,8 @@ $ rake db:migrate VERSION=20080906120000
If version 20080906120000 is greater than the current version (i.e., it is
migrating upwards), this will run the +up+ method on all migrations up to and
-including 20080906120000, and will not execute any later migrations. If
-migrating downwards, this will run the +down+ method on all the migrations
+including 20080906120000, and will not execute any later migrations. If
+migrating downwards, this will run the +down+ method on all the migrations
down to, but not including, 20080906120000.
h4. Rolling Back
@@ -627,13 +625,13 @@ A migration creating a table and adding an index might produce output like this
Several methods are provided in migrations that allow you to control all this:
|_.Method |_.Purpose|
-|suppress_messages |takes a block as an argument and suppresses any output
+|suppress_messages |Takes a block as an argument and suppresses any output
generated by the block.|
|say |Takes a message argument and outputs it as is. A second
boolean argument can be passed to specify whether to
indent or not.|
|say_with_time |Outputs text along with how long it took to run its
- block. If the block returns an integer it assumes it
+ block. If the block returns an integer it assumes it
is the number of rows affected.|
For example, this migration
@@ -771,7 +769,7 @@ If Alice had done this instead, there would have been no problem:
<ruby>
# db/migrate/20100513121110_add_flag_to_product.rb
-class AddFlagToProduct < ActiveRecord::Migration
+class AddFlagToProduct < ActiveRecord::Migration
class Product < ActiveRecord::Base
end
@@ -791,7 +789,7 @@ end
class AddFuzzToProduct < ActiveRecord::Migration
class Product < ActiveRecord::Base
end
-
+
def change
add_column :products, :fuzz, :string
Product.reset_column_information
@@ -807,7 +805,7 @@ h3. Schema Dumping and You
h4. What are Schema Files for?
Migrations, mighty as they may be, are not the authoritative source for your
-database schema. That role falls to either +db/schema.rb+ or a SQL file which
+database schema. That role falls to either +db/schema.rb+ or an SQL file which
Active Record generates by examining the database. They are not designed to be
edited, they just represent the current state of the database.
@@ -821,10 +819,10 @@ loaded into the test database.
Schema files are also useful if you want a quick look at what attributes an
Active Record object has. This information is not in the model's code and is
-frequently spread across several migrations, but the information is nicely
-summed up in the schema file. The
-"annotate_models":https://github.com/ctran/annotate_models gem automatically
-adds and updates comments at the top of each model summarizing the schema if
+frequently spread across several migrations, but the information is nicely
+summed up in the schema file. The
+"annotate_models":https://github.com/ctran/annotate_models gem automatically
+adds and updates comments at the top of each model summarizing the schema if
you desire that functionality.
h4. Types of Schema Dumps
@@ -867,8 +865,8 @@ reconstitute those statements from the database. If you are using features like
this, then you should set the schema format to +:sql+.
Instead of using Active Record's schema dumper, the database's structure will be
-dumped using a tool specific to the database (via the +db:structure:dump+ Rake
-task) into +db/structure.sql+. For example, for the PostgreSQL RDBMS, the
+dumped using a tool specific to the database (via the +db:structure:dump+ Rake task)
+into +db/structure.sql+. For example, for the PostgreSQL RDBMS, the
+pg_dump+ utility is used. For MySQL, this file will contain the output of +SHOW
CREATE TABLE+ for the various tables. Loading these schemas is simply a question
of executing the SQL statements they contain. By definition, this will create a