Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge branch 'master' of git@github.com:lifo/docrails

  • Loading branch information...
commit d551d9e68bdd9cb1ef5d0e552646576d035f8204 2 parents 65c6e22 + 5ad2bce
@miloops miloops authored
View
25 railties/doc/guides/migrations/anatomy_of_a_migration.txt
@@ -1,6 +1,6 @@
== Anatomy Of A Migration ==
-Before I dive into the details of a migration, here is a typical example:
+Before I dive into the details of a migration, here are a few examples of the sorts of things you can do:
[source, ruby]
------------------------
@@ -22,6 +22,29 @@ 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.
+Migrations are not limited to changing the schema. You can also use them to fix bad data in the database or populate new fields:
+
+[source, ruby]
+------------------------
+class AddReceiveNewsletterToUsers < ActiveRecord::Migration
+ def self.up
+ change_table :users do |t|
+ t.boolean :receive_newsletter, :default => false
+ end
+ User.update_all ["receive_newsletter = ?", true]
+ end
+
+ def self.down
+ remove_column :users, :receive_newsletter
+ end
+end
+------------------------
+
+This migration adds an `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.
+
+NOTE: Some <<models,caveats>> apply to using models in your migrations.
+
=== 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).
View
2  railties/doc/guides/migrations/foreign_keys.txt
@@ -1,5 +1,5 @@
-== Active Record and Referential Integrity ==
[[foreign_key]]
+== Active Record and Referential Integrity ==
The Active Record way is that intelligence belongs in your models, not in the database. As such features such as triggers or foreign key constraints, which push some of that intelligence back into the database are not heavily used.
Validations such as `validates_uniqueness_of` are one way in which models can enforce data integrity. The `:dependent` option on associations allows models to automatically destroy child objects when the parent is destroyed. These cannot however guarantee referential integrity and so some people augment them with foreign key constraints.
View
4 railties/doc/guides/migrations/scheming.txt
@@ -7,6 +7,8 @@ There is no need (and it is error prone) to deploy a new instance of an app by r
For example, this is how the test database is created: the current development database is dumped (either to `schema.rb` or `development.sql`) and then loaded.
+Schema files are also useful if 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 is all summed up in the schema file. The http://agilewebdevelopment.com/plugins/annotate_models[annotate_models] plugin, which automatically adds (and updates) comments at the top of each model summarising the schema, may also be of interest.
+
=== Types of schema dumps ===
There are two ways to dump the schema. This is set in `config/environment.rb` by the `config.active_record.schema_format` setting, which may be either `:sql` or `:ruby`.
@@ -35,7 +37,7 @@ In many ways this is exactly what it is. This file is created by inspecting the
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 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.
+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.
View
2  railties/doc/guides/migrations/using_models_in_migrations.txt
@@ -1,5 +1,5 @@
+[[models]]
== Using Models In Your Migrations ==
-
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 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:
Please sign in to comment.
Something went wrong with that request. Please try again.