Permalink
Browse files

Fixed many typos

  • Loading branch information...
1 parent 1a8edd3 commit c6da7c536c13555eba6aca82e0b5385b86b21211 @fcheung fcheung committed Sep 11, 2008
@@ -20,7 +20,7 @@ class CreateProducts < ActiveRecord::Migration
end
------------------------
-This migration adds a table called products with a string column called `name` and a text column called `description`. A primary key column called `id` will also be added, however since this is the default we do not need to ask for this. The timestamp columns `created_at` and `updated_at` which Active Record populates automatically will also be added. Reversing this migration is as simple as dropping the table.
+This migration adds a table called `products` with a string column called `name` and a text column called `description`. A primary key column called `id` will also be added, however since this is the default we do not need to ask for this. The timestamp columns `created_at` and `updated_at` which Active Record populates automatically will also be added. Reversing this migration is as simple as dropping the table.
=== Migrations are classes
A migration is a subclass of ActiveRecord::Migration that implements two class methods: +up+ (perform the required transformations) and +down+ (revert them).
@@ -37,7 +37,7 @@ Active Record provides methods that perform common data definition tasks in a da
* `add_index`
* `remove_index`
-If you need to perform tasks specific to your database (for example create a <<foreign_key,foreign key>> constraint) then the `execute` function allows you to execute arbitrary SQL. A migration is just a regular ruby class so you're not limited to these functions. For example after adding a column you could
+If you need to perform tasks specific to your database (for example create a <<foreign_key,foreign key>> constraint) then the `execute` function allows you to execute arbitrary SQL. A migration is just a regular Ruby class so you're not limited to these functions. For example after adding a column you could
write code to set the value of that column for existing records (if necessary using your models).
On databases that support transactions with statements that change the schema, migrations are wrapped in a transaction. If the database does not support this (for example Mysql and SQLite) then when a migration fails the parts of it that succeeded will not be rolled back. You will have to unpick the changes that were made by hand.
@@ -46,7 +46,7 @@ On databases that support transactions with statements that change the schema, m
Migrations are stored in files in `db/migrate`, 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 migration class' name must match (the camelcased version of) the latter part of the file name. For example `20080906120000_create_products.rb` should define CreateProducts and `20080906120001_add_details_to_products.rb` should define AddDetailsToProducts. If you do feel the need to change the file name then you MUST update the name of the class inside or Rails will complain about a missing class.
-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 to identify them.
+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 to identify them. You can revert to the old numbering scheme by setting `config.active_record.timestamped_migrations` to `false` in `environment.rb`.
The combination of timestamps and recording which migrations have been run allows Rails to handle common situations that occur with multiple developers.
@@ -25,7 +25,7 @@ end
-----------------------
You can append as many column name/type pairs as you want. By default `t.timestamps` (which creates the `updated_at` and `created_at` columns that
-are automatically populated by Active Record are also created) will be added for you.
+are automatically populated by Active Record) will be added for you.
=== 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 use the migration generator:
@@ -3,14 +3,14 @@ Migrations
Migrations are a convenient way for you to alter your database in a structured and organised manner. You could edit fragments of SQL by hand but you would then be responsible for telling other developers that they need to go and run it. You'd also have to keep track of which changes need to be run against the production machines next time you deploy. Active Record tracks which migrations have already been run so all you have to do is update your source and run `rake db:migrate`. Active Record will work out which migrations should be run.
-Migrations also allow you to describe these transformations using ruby. The great thing about this is that (like most of Active Record's functionality) its database independent, you don't need to worry about the precise syntax of CREATE TABLE any more that you worry about variations on SELECT * (you can drop down to raw SQL for database specific features). For example you could use SQLite3 in development, but MySQL in production.
+Migrations also allow you to describe these transformations using Ruby. The great thing about this is that (like most of Active Record's functionality) it's database independent, you don't need to worry about the precise syntax of CREATE TABLE any more that you worry about variations on SELECT * (you can drop down to raw SQL for database specific features). For example you could use SQLite3 in development, but MySQL in production.
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
-* How they relate to schema.rb
+* How they relate to `schema.rb`
include::anatomy_of_a_migration.txt[]
include::creating_a_migration.txt[]
@@ -1,13 +1,13 @@
== Running Migrations ==
-Rails provides a set of rake tasks to work with migrations which boils down to running certain sets of migrations. The very first migration related rake task you use will probably be `db:migrate`. In its most basic form it just runs the up method for all the migrations that have not yet been run. If there are no such migrations it exits.
+Rails provides a set of rake tasks to work with migrations which boils down to running certain sets of migrations. The very first migration related rake task you use will probably be `db:migrate`. In its most basic form it just runs the `up` method for all the migrations that have not yet been run. If there are no such migrations it exits.
-If you specify a target version. Active Record will run the required migrations (up or down) until it has reached the specified version. The
+If you specify a target version, Active Record will run the required migrations (up or down) 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
`rake db:migrate VERSION=20080906120000`
-If this is greater than the current version (i.e. it is migrating upwards) this will run all the up method on all migrations up to and including 20080906120000, if migrating downwards this will run the down method on all the migrations down to, but not including, 20080906120000.
+If this 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, if migrating downwards this will run the `down` method on all the migrations down to, but not including, 20080906120000.
Almost all the functionality provided by other rake tasks could be done using `db:migrate` but would be more tedious (partly because of the long version numbers you would have to lookup and enter).
@@ -17,11 +17,11 @@ A common task is to rollback the last migration, for example if you made a mista
`rake db:rollback`
-This will run the down method from the latest migration. If you need to undo several migrations you can provide a `STEP` parameter:
+This will run the `down` method from the latest migration. If you need to undo several migrations you can provide a `STEP` parameter:
`rake db:rollback STEP=3`
-will run the down method fron the last 3 migrations.
+will run the `down` method fron the last 3 migrations.
The `db:migrate:redo` task is a shortcut for doing a rollback and then migrating back up again. As with the `db:rollback` task you can use the `STEP` parameter if you need to go more than one version back, for example
@@ -33,11 +33,11 @@ NOTE: this is not the same as running all the migrations - see the section on <<
=== Being Specific ===
-If you need to run a specific migration up or down the `db:migrate:up` and `db:migrate:down` tasks will do that. Just specify the appropriate version and the corresponding migration will have its up or down method invoked, for example
+If you need to run a specific migration up or down the `db:migrate:up` and `db:migrate:down` tasks will do that. Just specify the appropriate version and the corresponding migration will have its `up` or `down` method invoked, for example
`rake db:migrate:up VERSION=20080906120000`
-will run the up method from the 20080906120000 migration. These tasks check whether the migration has already run, so for example `db:migrate:up VERSION=20080906120000` will do nothing if Active Record believes that 20080906120000 has already been run.
+will run the `up` method from the 20080906120000 migration. These tasks check whether the migration has already run, so for example `db:migrate:up VERSION=20080906120000` will do nothing if Active Record believes that 20080906120000 has already been run.
=== Being talkative ===
@@ -1,7 +1,7 @@
== Schema dumping and you ==
[[schema]]
=== 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 `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.
+Migrations, mighty as they may be, are not the authoritative source for your database schema. That role falls to either `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.
There is no need (and it is error prone) to deploy a new instance of an app by replaying the entire migration history. It is much simpler and faster to just load into the database a description of the current schema.
@@ -33,9 +33,9 @@ end
In many ways this is exactly what it is. This file is created by inspecting the database and expressing its structure using `create_table`, `add_index` and so on. Because this is database independent it could be loaded into any database that Active Record supports. This could be very useful if you were to distribute an application that is able to run against multiple databases.
-There is however a trade-off: `schema.rb` cannot express database specific items such as foreign key constraints, triggers or stored procedures. While in a migration you can execute custom sql statements, the schema dumper cannot reconstitute those statements from the database. If you are using features like this then you should set the schema format to `:sql`.
+There is however a trade-off: `schema.rb` cannot express database specific items such as foreign key constraints, triggers or stored procedures. While in a migration you can execute custom SQL statements, the schema dumper cannot 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 dumped using a tool specific to that database (via the `db:structure:dump` rake task) into `db/#\{RAILS_ENV\}_structure.sql`. For example for postgresql the `pg_dump` utility is used and for mysql this file will contain the output of SHOW CREATE TABLE for the various tables. Loading this schema is simply a question of executing the sql statements contained inside.
+Instead of using Active Record 's schema dumper the database's structure will be dumped using a tool specific to that database (via the `db:structure:dump` rake task) into `db/#\{RAILS_ENV\}_structure.sql`. For example for PostgreSQL the `pg_dump` utility is used and for MySQL this file will contain the output of SHOW CREATE TABLE for the various tables. Loading this schema is simply a question of executing the SQL statements contained inside.
By definition this will be a perfect copy of the database's structure but this will usually prevent loading the schema into a database other than the one used to create it.
@@ -2,7 +2,7 @@
When creating or updating data in a migration it is often tempting to use one of your models. After all they exist to provide easy access to the underlying data. This can be done but some caution should be observed. Consider for example a migration that uses the Product model to update a row in the corresponding table. Alice later updates the Product model, adding a new column and a validation on it. Bob comes back from holiday, updates the source and runs outstanding migrations with `rake db:migrate`, including the one that used the Product model. When the migration runs the source is up to date and so the Product model has the validation added by Alice. The database however is still old and so does not have that column and an error ensues.
-Frequently I just want to update rows in the database without writing out the sql by hand: I'm notusing anything specific to the model. One pattern for this is to define a copy of the model inside the migration itself, for example:
+Frequently I just want to update rows in the database without writing out the SQL by hand: I'm not using anything specific to the model. One pattern for this is to define a copy of the model inside the migration itself, for example:
[source, ruby]
-------------------------
@@ -12,7 +12,7 @@ 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).
+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
@@ -120,15 +120,15 @@ 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,foreign key>> constraints for you. You will need to use execute for that.
+NOTE: The `references` helper does not actually create <<foreign_key,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
+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
[source, ruby]
---------------------
@@ -154,6 +154,6 @@ class ExampleMigration < ActiveRecord::Migration
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
+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.

0 comments on commit c6da7c5

Please sign in to comment.