rails_test 4.2.0.beta1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/README.md +83 -0
- data/guides/CHANGELOG.md +27 -0
- data/guides/Rakefile +77 -0
- data/guides/assets/images/akshaysurve.jpg +0 -0
- data/guides/assets/images/belongs_to.png +0 -0
- data/guides/assets/images/book_icon.gif +0 -0
- data/guides/assets/images/bullet.gif +0 -0
- data/guides/assets/images/chapters_icon.gif +0 -0
- data/guides/assets/images/check_bullet.gif +0 -0
- data/guides/assets/images/credits_pic_blank.gif +0 -0
- data/guides/assets/images/csrf.png +0 -0
- data/guides/assets/images/edge_badge.png +0 -0
- data/guides/assets/images/favicon.ico +0 -0
- data/guides/assets/images/feature_tile.gif +0 -0
- data/guides/assets/images/footer_tile.gif +0 -0
- data/guides/assets/images/fxn.png +0 -0
- data/guides/assets/images/getting_started/article_with_comments.png +0 -0
- data/guides/assets/images/getting_started/challenge.png +0 -0
- data/guides/assets/images/getting_started/confirm_dialog.png +0 -0
- data/guides/assets/images/getting_started/forbidden_attributes_for_new_article.png +0 -0
- data/guides/assets/images/getting_started/form_with_errors.png +0 -0
- data/guides/assets/images/getting_started/index_action_with_edit_link.png +0 -0
- data/guides/assets/images/getting_started/new_article.png +0 -0
- data/guides/assets/images/getting_started/rails_welcome.png +0 -0
- data/guides/assets/images/getting_started/routing_error_no_controller.png +0 -0
- data/guides/assets/images/getting_started/routing_error_no_route_matches.png +0 -0
- data/guides/assets/images/getting_started/show_action_for_articles.png +0 -0
- data/guides/assets/images/getting_started/template_is_missing_articles_new.png +0 -0
- data/guides/assets/images/getting_started/unknown_action_create_for_articles.png +0 -0
- data/guides/assets/images/getting_started/unknown_action_new_for_articles.png +0 -0
- data/guides/assets/images/grey_bullet.gif +0 -0
- data/guides/assets/images/habtm.png +0 -0
- data/guides/assets/images/has_many.png +0 -0
- data/guides/assets/images/has_many_through.png +0 -0
- data/guides/assets/images/has_one.png +0 -0
- data/guides/assets/images/has_one_through.png +0 -0
- data/guides/assets/images/header_backdrop.png +0 -0
- data/guides/assets/images/header_tile.gif +0 -0
- data/guides/assets/images/i18n/demo_html_safe.png +0 -0
- data/guides/assets/images/i18n/demo_localized_pirate.png +0 -0
- data/guides/assets/images/i18n/demo_translated_en.png +0 -0
- data/guides/assets/images/i18n/demo_translated_pirate.png +0 -0
- data/guides/assets/images/i18n/demo_translation_missing.png +0 -0
- data/guides/assets/images/i18n/demo_untranslated.png +0 -0
- data/guides/assets/images/icons/README +5 -0
- data/guides/assets/images/icons/callouts/1.png +0 -0
- data/guides/assets/images/icons/callouts/10.png +0 -0
- data/guides/assets/images/icons/callouts/11.png +0 -0
- data/guides/assets/images/icons/callouts/12.png +0 -0
- data/guides/assets/images/icons/callouts/13.png +0 -0
- data/guides/assets/images/icons/callouts/14.png +0 -0
- data/guides/assets/images/icons/callouts/15.png +0 -0
- data/guides/assets/images/icons/callouts/2.png +0 -0
- data/guides/assets/images/icons/callouts/3.png +0 -0
- data/guides/assets/images/icons/callouts/4.png +0 -0
- data/guides/assets/images/icons/callouts/5.png +0 -0
- data/guides/assets/images/icons/callouts/6.png +0 -0
- data/guides/assets/images/icons/callouts/7.png +0 -0
- data/guides/assets/images/icons/callouts/8.png +0 -0
- data/guides/assets/images/icons/callouts/9.png +0 -0
- data/guides/assets/images/icons/caution.png +0 -0
- data/guides/assets/images/icons/example.png +0 -0
- data/guides/assets/images/icons/home.png +0 -0
- data/guides/assets/images/icons/important.png +0 -0
- data/guides/assets/images/icons/next.png +0 -0
- data/guides/assets/images/icons/note.png +0 -0
- data/guides/assets/images/icons/prev.png +0 -0
- data/guides/assets/images/icons/tip.png +0 -0
- data/guides/assets/images/icons/up.png +0 -0
- data/guides/assets/images/icons/warning.png +0 -0
- data/guides/assets/images/nav_arrow.gif +0 -0
- data/guides/assets/images/oscardelben.jpg +0 -0
- data/guides/assets/images/polymorphic.png +0 -0
- data/guides/assets/images/radar.png +0 -0
- data/guides/assets/images/rails4_features.png +0 -0
- data/guides/assets/images/rails_guides_kindle_cover.jpg +0 -0
- data/guides/assets/images/rails_guides_logo.gif +0 -0
- data/guides/assets/images/rails_logo_remix.gif +0 -0
- data/guides/assets/images/session_fixation.png +0 -0
- data/guides/assets/images/tab_grey.gif +0 -0
- data/guides/assets/images/tab_info.gif +0 -0
- data/guides/assets/images/tab_note.gif +0 -0
- data/guides/assets/images/tab_red.gif +0 -0
- data/guides/assets/images/tab_yellow.gif +0 -0
- data/guides/assets/images/tab_yellow.png +0 -0
- data/guides/assets/images/vijaydev.jpg +0 -0
- data/guides/assets/javascripts/guides.js +59 -0
- data/guides/assets/javascripts/jquery.min.js +4 -0
- data/guides/assets/javascripts/responsive-tables.js +43 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushAS3.js +59 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushAppleScript.js +75 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushBash.js +59 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushCSharp.js +65 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushColdFusion.js +100 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushCpp.js +97 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushCss.js +91 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushDelphi.js +55 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushDiff.js +41 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushErlang.js +52 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushGroovy.js +67 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushJScript.js +52 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushJava.js +57 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushJavaFX.js +58 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushPerl.js +72 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushPhp.js +88 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushPlain.js +33 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushPowerShell.js +74 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushPython.js +64 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushRuby.js +55 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushSass.js +94 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushScala.js +51 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushSql.js +66 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushVb.js +56 -0
- data/guides/assets/javascripts/syntaxhighlighter/shBrushXml.js +69 -0
- data/guides/assets/javascripts/syntaxhighlighter/shCore.js +17 -0
- data/guides/assets/stylesheets/fixes.css +16 -0
- data/guides/assets/stylesheets/kindle.css +11 -0
- data/guides/assets/stylesheets/main.css +713 -0
- data/guides/assets/stylesheets/print.css +52 -0
- data/guides/assets/stylesheets/reset.css +43 -0
- data/guides/assets/stylesheets/responsive-tables.css +50 -0
- data/guides/assets/stylesheets/style.css +13 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shCore.css +226 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shCoreDefault.css +328 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shCoreDjango.css +331 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shCoreEclipse.css +339 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shCoreEmacs.css +324 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shCoreFadeToGrey.css +328 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shCoreMDUltra.css +324 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shCoreMidnight.css +324 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shCoreRDark.css +324 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shThemeDefault.css +117 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shThemeDjango.css +120 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shThemeEclipse.css +128 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shThemeEmacs.css +113 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shThemeFadeToGrey.css +117 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shThemeMDUltra.css +113 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shThemeMidnight.css +113 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shThemeRDark.css +113 -0
- data/guides/assets/stylesheets/syntaxhighlighter/shThemeRailsGuides.css +116 -0
- data/guides/bug_report_templates/action_controller_gem.rb +47 -0
- data/guides/bug_report_templates/action_controller_master.rb +56 -0
- data/guides/bug_report_templates/active_record_gem.rb +40 -0
- data/guides/bug_report_templates/active_record_master.rb +51 -0
- data/guides/rails_guides.rb +63 -0
- data/guides/rails_guides/generator.rb +248 -0
- data/guides/rails_guides/helpers.rb +53 -0
- data/guides/rails_guides/indexer.rb +68 -0
- data/guides/rails_guides/kindle.rb +119 -0
- data/guides/rails_guides/levenshtein.rb +39 -0
- data/guides/rails_guides/markdown.rb +167 -0
- data/guides/rails_guides/markdown/renderer.rb +82 -0
- data/guides/source/2_2_release_notes.md +435 -0
- data/guides/source/2_3_release_notes.md +621 -0
- data/guides/source/3_0_release_notes.md +611 -0
- data/guides/source/3_1_release_notes.md +559 -0
- data/guides/source/3_2_release_notes.md +568 -0
- data/guides/source/4_0_release_notes.md +279 -0
- data/guides/source/4_1_release_notes.md +730 -0
- data/guides/source/4_2_release_notes.md +736 -0
- data/guides/source/_license.html.erb +2 -0
- data/guides/source/_welcome.html.erb +19 -0
- data/guides/source/action_controller_overview.md +1247 -0
- data/guides/source/action_mailer_basics.md +738 -0
- data/guides/source/action_view_overview.md +1621 -0
- data/guides/source/active_job_basics.md +285 -0
- data/guides/source/active_model_basics.md +223 -0
- data/guides/source/active_record_basics.md +374 -0
- data/guides/source/active_record_callbacks.md +413 -0
- data/guides/source/active_record_migrations.md +1016 -0
- data/guides/source/active_record_postgresql.md +438 -0
- data/guides/source/active_record_querying.md +1785 -0
- data/guides/source/active_record_validations.md +1169 -0
- data/guides/source/active_support_core_extensions.md +3924 -0
- data/guides/source/active_support_instrumentation.md +497 -0
- data/guides/source/api_documentation_guidelines.md +361 -0
- data/guides/source/asset_pipeline.md +1361 -0
- data/guides/source/association_basics.md +2238 -0
- data/guides/source/caching_with_rails.md +379 -0
- data/guides/source/command_line.md +634 -0
- data/guides/source/configuring.md +1019 -0
- data/guides/source/contributing_to_ruby_on_rails.md +607 -0
- data/guides/source/credits.html.erb +80 -0
- data/guides/source/debugging_rails_applications.md +861 -0
- data/guides/source/development_dependencies_install.md +289 -0
- data/guides/source/documents.yaml +197 -0
- data/guides/source/engines.md +1401 -0
- data/guides/source/form_helpers.md +1010 -0
- data/guides/source/generators.md +676 -0
- data/guides/source/getting_started.md +2085 -0
- data/guides/source/i18n.md +1073 -0
- data/guides/source/index.html.erb +28 -0
- data/guides/source/initialization.md +704 -0
- data/guides/source/kindle/copyright.html.erb +1 -0
- data/guides/source/kindle/layout.html.erb +27 -0
- data/guides/source/kindle/rails_guides.opf.erb +52 -0
- data/guides/source/kindle/toc.html.erb +24 -0
- data/guides/source/kindle/toc.ncx.erb +64 -0
- data/guides/source/kindle/welcome.html.erb +5 -0
- data/guides/source/layout.html.erb +143 -0
- data/guides/source/layouts_and_rendering.md +1227 -0
- data/guides/source/maintenance_policy.md +75 -0
- data/guides/source/nested_model_forms.md +228 -0
- data/guides/source/plugins.md +444 -0
- data/guides/source/rails_application_templates.md +266 -0
- data/guides/source/rails_on_rack.md +332 -0
- data/guides/source/routing.md +1141 -0
- data/guides/source/ruby_on_rails_guides_guidelines.md +126 -0
- data/guides/source/security.md +1024 -0
- data/guides/source/testing.md +1055 -0
- data/guides/source/upgrading_ruby_on_rails.md +1046 -0
- data/guides/source/working_with_javascript_in_rails.md +407 -0
- data/guides/w3c_validator.rb +97 -0
- metadata +404 -0
@@ -0,0 +1,1016 @@
|
|
1
|
+
Active Record Migrations
|
2
|
+
========================
|
3
|
+
|
4
|
+
Migrations are a feature of Active Record that allows you to evolve your
|
5
|
+
database schema over time. Rather than write schema modifications in pure SQL,
|
6
|
+
migrations allow you to use an easy Ruby DSL to describe changes to your
|
7
|
+
tables.
|
8
|
+
|
9
|
+
After reading this guide, you will know:
|
10
|
+
|
11
|
+
* The generators you can use to create them.
|
12
|
+
* The methods Active Record provides to manipulate your database.
|
13
|
+
* The Rake tasks that manipulate migrations and your schema.
|
14
|
+
* How migrations relate to `schema.rb`.
|
15
|
+
|
16
|
+
--------------------------------------------------------------------------------
|
17
|
+
|
18
|
+
Migration Overview
|
19
|
+
------------------
|
20
|
+
|
21
|
+
Migrations are a convenient way to
|
22
|
+
[alter your database schema over time](http://en.wikipedia.org/wiki/Schema_migration)
|
23
|
+
in a consistent and easy way. They use a Ruby DSL so that you don't have to
|
24
|
+
write SQL by hand, allowing your schema and changes to be database independent.
|
25
|
+
|
26
|
+
You can think of each migration as being a new 'version' of the database. A
|
27
|
+
schema starts off with nothing in it, and each migration modifies it to add or
|
28
|
+
remove tables, columns, or entries. Active Record knows how to update your
|
29
|
+
schema along this timeline, bringing it from whatever point it is in the
|
30
|
+
history to the latest version. Active Record will also update your
|
31
|
+
`db/schema.rb` file to match the up-to-date structure of your database.
|
32
|
+
|
33
|
+
Here's an example of a migration:
|
34
|
+
|
35
|
+
```ruby
|
36
|
+
class CreateProducts < ActiveRecord::Migration
|
37
|
+
def change
|
38
|
+
create_table :products do |t|
|
39
|
+
t.string :name
|
40
|
+
t.text :description
|
41
|
+
|
42
|
+
t.timestamps
|
43
|
+
end
|
44
|
+
end
|
45
|
+
end
|
46
|
+
```
|
47
|
+
|
48
|
+
This migration adds a table called `products` with a string column called
|
49
|
+
`name` and a text column called `description`. A primary key column called `id`
|
50
|
+
will also be added implicitly, as it's the default primary key for all Active
|
51
|
+
Record models. The `timestamps` macro adds two columns, `created_at` and
|
52
|
+
`updated_at`. These special columns are automatically managed by Active Record
|
53
|
+
if they exist.
|
54
|
+
|
55
|
+
Note that we define the change that we want to happen moving forward in time.
|
56
|
+
Before this migration is run, there will be no table. After, the table will
|
57
|
+
exist. Active Record knows how to reverse this migration as well: if we roll
|
58
|
+
this migration back, it will remove the table.
|
59
|
+
|
60
|
+
On databases that support transactions with statements that change the schema,
|
61
|
+
migrations are wrapped in a transaction. If the database does not support this
|
62
|
+
then when a migration fails the parts of it that succeeded will not be rolled
|
63
|
+
back. You will have to rollback the changes that were made by hand.
|
64
|
+
|
65
|
+
NOTE: There are certain queries that can't run inside a transaction. If your
|
66
|
+
adapter supports DDL transactions you can use `disable_ddl_transaction!` to
|
67
|
+
disable them for a single migration.
|
68
|
+
|
69
|
+
If you wish for a migration to do something that Active Record doesn't know how
|
70
|
+
to reverse, you can use `reversible`:
|
71
|
+
|
72
|
+
```ruby
|
73
|
+
class ChangeProductsPrice < ActiveRecord::Migration
|
74
|
+
def change
|
75
|
+
reversible do |dir|
|
76
|
+
change_table :products do |t|
|
77
|
+
dir.up { t.change :price, :string }
|
78
|
+
dir.down { t.change :price, :integer }
|
79
|
+
end
|
80
|
+
end
|
81
|
+
end
|
82
|
+
end
|
83
|
+
```
|
84
|
+
|
85
|
+
Alternatively, you can use `up` and `down` instead of `change`:
|
86
|
+
|
87
|
+
```ruby
|
88
|
+
class ChangeProductsPrice < ActiveRecord::Migration
|
89
|
+
def up
|
90
|
+
change_table :products do |t|
|
91
|
+
t.change :price, :string
|
92
|
+
end
|
93
|
+
end
|
94
|
+
|
95
|
+
def down
|
96
|
+
change_table :products do |t|
|
97
|
+
t.change :price, :integer
|
98
|
+
end
|
99
|
+
end
|
100
|
+
end
|
101
|
+
```
|
102
|
+
|
103
|
+
Creating a Migration
|
104
|
+
--------------------
|
105
|
+
|
106
|
+
### Creating a Standalone Migration
|
107
|
+
|
108
|
+
Migrations are stored as files in the `db/migrate` directory, one for each
|
109
|
+
migration class. The name of the file is of the form
|
110
|
+
`YYYYMMDDHHMMSS_create_products.rb`, that is to say a UTC timestamp
|
111
|
+
identifying the migration followed by an underscore followed by the name
|
112
|
+
of the migration. The name of the migration class (CamelCased version)
|
113
|
+
should match the latter part of the file name. For example
|
114
|
+
`20080906120000_create_products.rb` should define class `CreateProducts` and
|
115
|
+
`20080906120001_add_details_to_products.rb` should define
|
116
|
+
`AddDetailsToProducts`. Rails uses this timestamp to determine which migration
|
117
|
+
should be run and in what order, so if you're copying a migration from another
|
118
|
+
application or generate a file yourself, be aware of its position in the order.
|
119
|
+
|
120
|
+
Of course, calculating timestamps is no fun, so Active Record provides a
|
121
|
+
generator to handle making it for you:
|
122
|
+
|
123
|
+
```bash
|
124
|
+
$ bin/rails generate migration AddPartNumberToProducts
|
125
|
+
```
|
126
|
+
|
127
|
+
This will create an empty but appropriately named migration:
|
128
|
+
|
129
|
+
```ruby
|
130
|
+
class AddPartNumberToProducts < ActiveRecord::Migration
|
131
|
+
def change
|
132
|
+
end
|
133
|
+
end
|
134
|
+
```
|
135
|
+
|
136
|
+
If the migration name is of the form "AddXXXToYYY" or "RemoveXXXFromYYY" and is
|
137
|
+
followed by a list of column names and types then a migration containing the
|
138
|
+
appropriate `add_column` and `remove_column` statements will be created.
|
139
|
+
|
140
|
+
```bash
|
141
|
+
$ bin/rails generate migration AddPartNumberToProducts part_number:string
|
142
|
+
```
|
143
|
+
|
144
|
+
will generate
|
145
|
+
|
146
|
+
```ruby
|
147
|
+
class AddPartNumberToProducts < ActiveRecord::Migration
|
148
|
+
def change
|
149
|
+
add_column :products, :part_number, :string
|
150
|
+
end
|
151
|
+
end
|
152
|
+
```
|
153
|
+
|
154
|
+
If you'd like to add an index on the new column, you can do that as well:
|
155
|
+
|
156
|
+
```bash
|
157
|
+
$ bin/rails generate migration AddPartNumberToProducts part_number:string:index
|
158
|
+
```
|
159
|
+
|
160
|
+
will generate
|
161
|
+
|
162
|
+
```ruby
|
163
|
+
class AddPartNumberToProducts < ActiveRecord::Migration
|
164
|
+
def change
|
165
|
+
add_column :products, :part_number, :string
|
166
|
+
add_index :products, :part_number
|
167
|
+
end
|
168
|
+
end
|
169
|
+
```
|
170
|
+
|
171
|
+
|
172
|
+
Similarly, you can generate a migration to remove a column from the command line:
|
173
|
+
|
174
|
+
```bash
|
175
|
+
$ bin/rails generate migration RemovePartNumberFromProducts part_number:string
|
176
|
+
```
|
177
|
+
|
178
|
+
generates
|
179
|
+
|
180
|
+
```ruby
|
181
|
+
class RemovePartNumberFromProducts < ActiveRecord::Migration
|
182
|
+
def change
|
183
|
+
remove_column :products, :part_number, :string
|
184
|
+
end
|
185
|
+
end
|
186
|
+
```
|
187
|
+
|
188
|
+
You are not limited to one magically generated column. For example:
|
189
|
+
|
190
|
+
```bash
|
191
|
+
$ bin/rails generate migration AddDetailsToProducts part_number:string price:decimal
|
192
|
+
```
|
193
|
+
|
194
|
+
generates
|
195
|
+
|
196
|
+
```ruby
|
197
|
+
class AddDetailsToProducts < ActiveRecord::Migration
|
198
|
+
def change
|
199
|
+
add_column :products, :part_number, :string
|
200
|
+
add_column :products, :price, :decimal
|
201
|
+
end
|
202
|
+
end
|
203
|
+
```
|
204
|
+
|
205
|
+
If the migration name is of the form "CreateXXX" and is
|
206
|
+
followed by a list of column names and types then a migration creating the table
|
207
|
+
XXX with the columns listed will be generated. For example:
|
208
|
+
|
209
|
+
```bash
|
210
|
+
$ bin/rails generate migration CreateProducts name:string part_number:string
|
211
|
+
```
|
212
|
+
|
213
|
+
generates
|
214
|
+
|
215
|
+
```ruby
|
216
|
+
class CreateProducts < ActiveRecord::Migration
|
217
|
+
def change
|
218
|
+
create_table :products do |t|
|
219
|
+
t.string :name
|
220
|
+
t.string :part_number
|
221
|
+
end
|
222
|
+
end
|
223
|
+
end
|
224
|
+
```
|
225
|
+
|
226
|
+
As always, what has been generated for you is just a starting point. You can add
|
227
|
+
or remove from it as you see fit by editing the
|
228
|
+
`db/migrate/YYYYMMDDHHMMSS_add_details_to_products.rb` file.
|
229
|
+
|
230
|
+
Also, the generator accepts column type as `references`(also available as
|
231
|
+
`belongs_to`). For instance:
|
232
|
+
|
233
|
+
```bash
|
234
|
+
$ bin/rails generate migration AddUserRefToProducts user:references
|
235
|
+
```
|
236
|
+
|
237
|
+
generates
|
238
|
+
|
239
|
+
```ruby
|
240
|
+
class AddUserRefToProducts < ActiveRecord::Migration
|
241
|
+
def change
|
242
|
+
add_reference :products, :user, index: true
|
243
|
+
end
|
244
|
+
end
|
245
|
+
```
|
246
|
+
|
247
|
+
This migration will create a `user_id` column and appropriate index.
|
248
|
+
|
249
|
+
There is also a generator which will produce join tables if `JoinTable` is part of the name:
|
250
|
+
|
251
|
+
```bash
|
252
|
+
$ bin/rails g migration CreateJoinTableCustomerProduct customer product
|
253
|
+
```
|
254
|
+
|
255
|
+
will produce the following migration:
|
256
|
+
|
257
|
+
```ruby
|
258
|
+
class CreateJoinTableCustomerProduct < ActiveRecord::Migration
|
259
|
+
def change
|
260
|
+
create_join_table :customers, :products do |t|
|
261
|
+
# t.index [:customer_id, :product_id]
|
262
|
+
# t.index [:product_id, :customer_id]
|
263
|
+
end
|
264
|
+
end
|
265
|
+
end
|
266
|
+
```
|
267
|
+
|
268
|
+
### Model Generators
|
269
|
+
|
270
|
+
The model and scaffold generators will create migrations appropriate for adding
|
271
|
+
a new model. This migration will already contain instructions for creating the
|
272
|
+
relevant table. If you tell Rails what columns you want, then statements for
|
273
|
+
adding these columns will also be created. For example, running:
|
274
|
+
|
275
|
+
```bash
|
276
|
+
$ bin/rails generate model Product name:string description:text
|
277
|
+
```
|
278
|
+
|
279
|
+
will create a migration that looks like this
|
280
|
+
|
281
|
+
```ruby
|
282
|
+
class CreateProducts < ActiveRecord::Migration
|
283
|
+
def change
|
284
|
+
create_table :products do |t|
|
285
|
+
t.string :name
|
286
|
+
t.text :description
|
287
|
+
|
288
|
+
t.timestamps
|
289
|
+
end
|
290
|
+
end
|
291
|
+
end
|
292
|
+
```
|
293
|
+
|
294
|
+
You can append as many column name/type pairs as you want.
|
295
|
+
|
296
|
+
### Passing Modifiers
|
297
|
+
|
298
|
+
Some commonly used [type modifiers](#column-modifiers) can be passed directly on
|
299
|
+
the command line. They are enclosed by curly braces and follow the field type:
|
300
|
+
|
301
|
+
For instance, running:
|
302
|
+
|
303
|
+
```bash
|
304
|
+
$ bin/rails generate migration AddDetailsToProducts 'price:decimal{5,2}' supplier:references{polymorphic}
|
305
|
+
```
|
306
|
+
|
307
|
+
will produce a migration that looks like this
|
308
|
+
|
309
|
+
```ruby
|
310
|
+
class AddDetailsToProducts < ActiveRecord::Migration
|
311
|
+
def change
|
312
|
+
add_column :products, :price, :decimal, precision: 5, scale: 2
|
313
|
+
add_reference :products, :supplier, polymorphic: true, index: true
|
314
|
+
end
|
315
|
+
end
|
316
|
+
```
|
317
|
+
|
318
|
+
TIP: Have a look at the generators help output for further details.
|
319
|
+
|
320
|
+
Writing a Migration
|
321
|
+
-------------------
|
322
|
+
|
323
|
+
Once you have created your migration using one of the generators it's time to
|
324
|
+
get to work!
|
325
|
+
|
326
|
+
### Creating a Table
|
327
|
+
|
328
|
+
The `create_table` method is one of the most fundamental, but most of the time,
|
329
|
+
will be generated for you from using a model or scaffold generator. A typical
|
330
|
+
use would be
|
331
|
+
|
332
|
+
```ruby
|
333
|
+
create_table :products do |t|
|
334
|
+
t.string :name
|
335
|
+
end
|
336
|
+
```
|
337
|
+
|
338
|
+
which creates a `products` table with a column called `name` (and as discussed
|
339
|
+
below, an implicit `id` column).
|
340
|
+
|
341
|
+
By default, `create_table` will create a primary key called `id`. You can change
|
342
|
+
the name of the primary key with the `:primary_key` option (don't forget to
|
343
|
+
update the corresponding model) or, if you don't want a primary key at all, you
|
344
|
+
can pass the option `id: false`. If you need to pass database specific options
|
345
|
+
you can place an SQL fragment in the `:options` option. For example:
|
346
|
+
|
347
|
+
```ruby
|
348
|
+
create_table :products, options: "ENGINE=BLACKHOLE" do |t|
|
349
|
+
t.string :name, null: false
|
350
|
+
end
|
351
|
+
```
|
352
|
+
|
353
|
+
will append `ENGINE=BLACKHOLE` to the SQL statement used to create the table
|
354
|
+
(when using MySQL, the default is `ENGINE=InnoDB`).
|
355
|
+
|
356
|
+
### Creating a Join Table
|
357
|
+
|
358
|
+
Migration method `create_join_table` creates a HABTM join table. A typical use
|
359
|
+
would be:
|
360
|
+
|
361
|
+
```ruby
|
362
|
+
create_join_table :products, :categories
|
363
|
+
```
|
364
|
+
|
365
|
+
which creates a `categories_products` table with two columns called
|
366
|
+
`category_id` and `product_id`. These columns have the option `:null` set to
|
367
|
+
`false` by default. This can be overridden by specifying the `:column_options`
|
368
|
+
option.
|
369
|
+
|
370
|
+
```ruby
|
371
|
+
create_join_table :products, :categories, column_options: {null: true}
|
372
|
+
```
|
373
|
+
|
374
|
+
will create the `product_id` and `category_id` with the `:null` option as
|
375
|
+
`true`.
|
376
|
+
|
377
|
+
You can pass the option `:table_name` when you want to customize the table
|
378
|
+
name. For example:
|
379
|
+
|
380
|
+
```ruby
|
381
|
+
create_join_table :products, :categories, table_name: :categorization
|
382
|
+
```
|
383
|
+
|
384
|
+
will create a `categorization` table.
|
385
|
+
|
386
|
+
`create_join_table` also accepts a block, which you can use to add indices
|
387
|
+
(which are not created by default) or additional columns:
|
388
|
+
|
389
|
+
```ruby
|
390
|
+
create_join_table :products, :categories do |t|
|
391
|
+
t.index :product_id
|
392
|
+
t.index :category_id
|
393
|
+
end
|
394
|
+
```
|
395
|
+
|
396
|
+
### Changing Tables
|
397
|
+
|
398
|
+
A close cousin of `create_table` is `change_table`, used for changing existing
|
399
|
+
tables. It is used in a similar fashion to `create_table` but the object
|
400
|
+
yielded to the block knows more tricks. For example:
|
401
|
+
|
402
|
+
```ruby
|
403
|
+
change_table :products do |t|
|
404
|
+
t.remove :description, :name
|
405
|
+
t.string :part_number
|
406
|
+
t.index :part_number
|
407
|
+
t.rename :upccode, :upc_code
|
408
|
+
end
|
409
|
+
```
|
410
|
+
|
411
|
+
removes the `description` and `name` columns, creates a `part_number` string
|
412
|
+
column and adds an index on it. Finally it renames the `upccode` column.
|
413
|
+
|
414
|
+
### Changing Columns
|
415
|
+
|
416
|
+
Like the `remove_column` and `add_column` Rails provides the `change_column`
|
417
|
+
migration method.
|
418
|
+
|
419
|
+
```ruby
|
420
|
+
change_column :products, :part_number, :text
|
421
|
+
```
|
422
|
+
|
423
|
+
This changes the column `part_number` on products table to be a `:text` field.
|
424
|
+
|
425
|
+
Besides `change_column`, the `change_column_null` and `change_column_default`
|
426
|
+
methods are used specifically to change the null and default values of a
|
427
|
+
column.
|
428
|
+
|
429
|
+
```ruby
|
430
|
+
change_column_null :products, :name, false
|
431
|
+
change_column_default :products, :approved, false
|
432
|
+
```
|
433
|
+
|
434
|
+
This sets `:name` field on products to a `NOT NULL` column and the default
|
435
|
+
value of the `:approved` field to false.
|
436
|
+
|
437
|
+
TIP: Unlike `change_column` (and `change_column_default`), `change_column_null`
|
438
|
+
is reversible.
|
439
|
+
|
440
|
+
### Column Modifiers
|
441
|
+
|
442
|
+
Column modifiers can be applied when creating or changing a column:
|
443
|
+
|
444
|
+
* `limit` Sets the maximum size of the `string/text/binary/integer` fields.
|
445
|
+
* `precision` Defines the precision for the `decimal` fields, representing the
|
446
|
+
total number of digits in the number.
|
447
|
+
* `scale` Defines the scale for the `decimal` fields, representing the
|
448
|
+
number of digits after the decimal point.
|
449
|
+
* `polymorphic` Adds a `type` column for `belongs_to` associations.
|
450
|
+
* `null` Allows or disallows `NULL` values in the column.
|
451
|
+
* `default` Allows to set a default value on the column. Note that if you
|
452
|
+
are using a dynamic value (such as a date), the default will only be calculated
|
453
|
+
the first time (i.e. on the date the migration is applied).
|
454
|
+
* `index` Adds an index for the column.
|
455
|
+
|
456
|
+
Some adapters may support additional options; see the adapter specific API docs
|
457
|
+
for further information.
|
458
|
+
|
459
|
+
### Foreign Keys
|
460
|
+
|
461
|
+
While it's not required you might want to add foreign key constraints to
|
462
|
+
[guarantee referential integrity](#active-record-and-referential-integrity).
|
463
|
+
|
464
|
+
```ruby
|
465
|
+
add_foreign_key :articles, :authors
|
466
|
+
```
|
467
|
+
|
468
|
+
This adds a new foreign key to the `author_id` column of the `articles`
|
469
|
+
table. The key references the `id` column of the `articles` table. If the
|
470
|
+
column names can not be derived from the table names, you can use the
|
471
|
+
`:column` and `:primary_key` options.
|
472
|
+
|
473
|
+
Rails will generate a name for every foreign key starting with
|
474
|
+
`fk_rails_` followed by 10 random characters.
|
475
|
+
There is a `:name` option to specify a different name if needed.
|
476
|
+
|
477
|
+
NOTE: Active Record only supports single column foreign keys. `execute` and
|
478
|
+
`structure.sql` are required to use composite foreign keys.
|
479
|
+
|
480
|
+
Removing a foreign key is easy as well:
|
481
|
+
|
482
|
+
```ruby
|
483
|
+
# let Active Record figure out the column name
|
484
|
+
remove_foreign_key :accounts, :branches
|
485
|
+
|
486
|
+
# remove foreign key for a specific column
|
487
|
+
remove_foreign_key :accounts, column: :owner_id
|
488
|
+
|
489
|
+
# remove foreign key by name
|
490
|
+
remove_foreign_key :accounts, name: :special_fk_name
|
491
|
+
```
|
492
|
+
|
493
|
+
### When Helpers aren't Enough
|
494
|
+
|
495
|
+
If the helpers provided by Active Record aren't enough you can use the `execute`
|
496
|
+
method to execute arbitrary SQL:
|
497
|
+
|
498
|
+
```ruby
|
499
|
+
Product.connection.execute('UPDATE `products` SET `price`=`free` WHERE 1')
|
500
|
+
```
|
501
|
+
|
502
|
+
For more details and examples of individual methods, check the API documentation.
|
503
|
+
In particular the documentation for
|
504
|
+
[`ActiveRecord::ConnectionAdapters::SchemaStatements`](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html)
|
505
|
+
(which provides the methods available in the `change`, `up` and `down` methods),
|
506
|
+
[`ActiveRecord::ConnectionAdapters::TableDefinition`](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html)
|
507
|
+
(which provides the methods available on the object yielded by `create_table`)
|
508
|
+
and
|
509
|
+
[`ActiveRecord::ConnectionAdapters::Table`](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html)
|
510
|
+
(which provides the methods available on the object yielded by `change_table`).
|
511
|
+
|
512
|
+
### Using the `change` Method
|
513
|
+
|
514
|
+
The `change` method is the primary way of writing migrations. It works for the
|
515
|
+
majority of cases, where Active Record knows how to reverse the migration
|
516
|
+
automatically. Currently, the `change` method supports only these migration
|
517
|
+
definitions:
|
518
|
+
|
519
|
+
* `add_column`
|
520
|
+
* `add_index`
|
521
|
+
* `add_reference`
|
522
|
+
* `add_timestamps`
|
523
|
+
* `add_foreign_key`
|
524
|
+
* `create_table`
|
525
|
+
* `create_join_table`
|
526
|
+
* `drop_table` (must supply a block)
|
527
|
+
* `drop_join_table` (must supply a block)
|
528
|
+
* `remove_timestamps`
|
529
|
+
* `rename_column`
|
530
|
+
* `rename_index`
|
531
|
+
* `remove_reference`
|
532
|
+
* `rename_table`
|
533
|
+
|
534
|
+
`change_table` is also reversible, as long as the block does not call `change`,
|
535
|
+
`change_default` or `remove`.
|
536
|
+
|
537
|
+
If you're going to need to use any other methods, you should use `reversible`
|
538
|
+
or write the `up` and `down` methods instead of using the `change` method.
|
539
|
+
|
540
|
+
### Using `reversible`
|
541
|
+
|
542
|
+
Complex migrations may require processing that Active Record doesn't know how
|
543
|
+
to reverse. You can use `reversible` to specify what to do when running a
|
544
|
+
migration what else to do when reverting it. For example:
|
545
|
+
|
546
|
+
```ruby
|
547
|
+
class ExampleMigration < ActiveRecord::Migration
|
548
|
+
def change
|
549
|
+
create_table :distributors do |t|
|
550
|
+
t.string :zipcode
|
551
|
+
end
|
552
|
+
|
553
|
+
reversible do |dir|
|
554
|
+
dir.up do
|
555
|
+
# add a CHECK constraint
|
556
|
+
execute <<-SQL
|
557
|
+
ALTER TABLE distributors
|
558
|
+
ADD CONSTRAINT zipchk
|
559
|
+
CHECK (char_length(zipcode) = 5) NO INHERIT;
|
560
|
+
SQL
|
561
|
+
end
|
562
|
+
dir.down do
|
563
|
+
execute <<-SQL
|
564
|
+
ALTER TABLE distributors
|
565
|
+
DROP CONSTRAINT zipchk
|
566
|
+
SQL
|
567
|
+
end
|
568
|
+
end
|
569
|
+
|
570
|
+
add_column :users, :home_page_url, :string
|
571
|
+
rename_column :users, :email, :email_address
|
572
|
+
end
|
573
|
+
end
|
574
|
+
```
|
575
|
+
|
576
|
+
Using `reversible` will ensure that the instructions are executed in the
|
577
|
+
right order too. If the previous example migration is reverted,
|
578
|
+
the `down` block will be run after the `home_page_url` column is removed and
|
579
|
+
right before the table `distributors` is dropped.
|
580
|
+
|
581
|
+
Sometimes your migration will do something which is just plain irreversible; for
|
582
|
+
example, it might destroy some data. In such cases, you can raise
|
583
|
+
`ActiveRecord::IrreversibleMigration` in your `down` block. If someone tries
|
584
|
+
to revert your migration, an error message will be displayed saying that it
|
585
|
+
can't be done.
|
586
|
+
|
587
|
+
### Using the `up`/`down` Methods
|
588
|
+
|
589
|
+
You can also use the old style of migration using `up` and `down` methods
|
590
|
+
instead of the `change` method.
|
591
|
+
The `up` method should describe the transformation you'd like to make to your
|
592
|
+
schema, and the `down` method of your migration should revert the
|
593
|
+
transformations done by the `up` method. In other words, the database schema
|
594
|
+
should be unchanged if you do an `up` followed by a `down`. For example, if you
|
595
|
+
create a table in the `up` method, you should drop it in the `down` method. It
|
596
|
+
is wise to reverse the transformations in precisely the reverse order they were
|
597
|
+
made in the `up` method. The example in the `reversible` section is equivalent to:
|
598
|
+
|
599
|
+
```ruby
|
600
|
+
class ExampleMigration < ActiveRecord::Migration
|
601
|
+
def up
|
602
|
+
create_table :distributors do |t|
|
603
|
+
t.string :zipcode
|
604
|
+
end
|
605
|
+
|
606
|
+
# add a CHECK constraint
|
607
|
+
execute <<-SQL
|
608
|
+
ALTER TABLE distributors
|
609
|
+
ADD CONSTRAINT zipchk
|
610
|
+
CHECK (char_length(zipcode) = 5);
|
611
|
+
SQL
|
612
|
+
|
613
|
+
add_column :users, :home_page_url, :string
|
614
|
+
rename_column :users, :email, :email_address
|
615
|
+
end
|
616
|
+
|
617
|
+
def down
|
618
|
+
rename_column :users, :email_address, :email
|
619
|
+
remove_column :users, :home_page_url
|
620
|
+
|
621
|
+
execute <<-SQL
|
622
|
+
ALTER TABLE distributors
|
623
|
+
DROP CONSTRAINT zipchk
|
624
|
+
SQL
|
625
|
+
|
626
|
+
drop_table :distributors
|
627
|
+
end
|
628
|
+
end
|
629
|
+
```
|
630
|
+
|
631
|
+
If your migration is irreversible, you should raise
|
632
|
+
`ActiveRecord::IrreversibleMigration` from your `down` method. If someone tries
|
633
|
+
to revert your migration, an error message will be displayed saying that it
|
634
|
+
can't be done.
|
635
|
+
|
636
|
+
### Reverting Previous Migrations
|
637
|
+
|
638
|
+
You can use Active Record's ability to rollback migrations using the `revert` method:
|
639
|
+
|
640
|
+
```ruby
|
641
|
+
require_relative '2012121212_example_migration'
|
642
|
+
|
643
|
+
class FixupExampleMigration < ActiveRecord::Migration
|
644
|
+
def change
|
645
|
+
revert ExampleMigration
|
646
|
+
|
647
|
+
create_table(:apples) do |t|
|
648
|
+
t.string :variety
|
649
|
+
end
|
650
|
+
end
|
651
|
+
end
|
652
|
+
```
|
653
|
+
|
654
|
+
The `revert` method also accepts a block of instructions to reverse.
|
655
|
+
This could be useful to revert selected parts of previous migrations.
|
656
|
+
For example, let's imagine that `ExampleMigration` is committed and it
|
657
|
+
is later decided it would be best to use Active Record validations,
|
658
|
+
in place of the `CHECK` constraint, to verify the zipcode.
|
659
|
+
|
660
|
+
```ruby
|
661
|
+
class DontUseConstraintForZipcodeValidationMigration < ActiveRecord::Migration
|
662
|
+
def change
|
663
|
+
revert do
|
664
|
+
# copy-pasted code from ExampleMigration
|
665
|
+
reversible do |dir|
|
666
|
+
dir.up do
|
667
|
+
# add a CHECK constraint
|
668
|
+
execute <<-SQL
|
669
|
+
ALTER TABLE distributors
|
670
|
+
ADD CONSTRAINT zipchk
|
671
|
+
CHECK (char_length(zipcode) = 5);
|
672
|
+
SQL
|
673
|
+
end
|
674
|
+
dir.down do
|
675
|
+
execute <<-SQL
|
676
|
+
ALTER TABLE distributors
|
677
|
+
DROP CONSTRAINT zipchk
|
678
|
+
SQL
|
679
|
+
end
|
680
|
+
end
|
681
|
+
|
682
|
+
# The rest of the migration was ok
|
683
|
+
end
|
684
|
+
end
|
685
|
+
end
|
686
|
+
```
|
687
|
+
|
688
|
+
The same migration could also have been written without using `revert`
|
689
|
+
but this would have involved a few more steps: reversing the order
|
690
|
+
of `create_table` and `reversible`, replacing `create_table`
|
691
|
+
by `drop_table`, and finally replacing `up` by `down` and vice-versa.
|
692
|
+
This is all taken care of by `revert`.
|
693
|
+
|
694
|
+
Running Migrations
|
695
|
+
------------------
|
696
|
+
|
697
|
+
Rails provides a set of Rake tasks to run certain sets of migrations.
|
698
|
+
|
699
|
+
The very first migration related Rake task you will use will probably be
|
700
|
+
`rake db:migrate`. In its most basic form it just runs the `change` or `up`
|
701
|
+
method for all the migrations that have not yet been run. If there are
|
702
|
+
no such migrations, it exits. It will run these migrations in order based
|
703
|
+
on the date of the migration.
|
704
|
+
|
705
|
+
Note that running the `db:migrate` task also invokes the `db:schema:dump` task, which
|
706
|
+
will update your `db/schema.rb` file to match the structure of your database.
|
707
|
+
|
708
|
+
If you specify a target version, Active Record will run the required migrations
|
709
|
+
(change, up, down) until it has reached the specified version. The version
|
710
|
+
is the numerical prefix on the migration's filename. For example, to migrate
|
711
|
+
to version 20080906120000 run:
|
712
|
+
|
713
|
+
```bash
|
714
|
+
$ bin/rake db:migrate VERSION=20080906120000
|
715
|
+
```
|
716
|
+
|
717
|
+
If version 20080906120000 is greater than the current version (i.e., it is
|
718
|
+
migrating upwards), this will run the `change` (or `up`) method
|
719
|
+
on all migrations up to and
|
720
|
+
including 20080906120000, and will not execute any later migrations. If
|
721
|
+
migrating downwards, this will run the `down` method on all the migrations
|
722
|
+
down to, but not including, 20080906120000.
|
723
|
+
|
724
|
+
### Rolling Back
|
725
|
+
|
726
|
+
A common task is to rollback the last migration. For example, if you made a
|
727
|
+
mistake in it and wish to correct it. Rather than tracking down the version
|
728
|
+
number associated with the previous migration you can run:
|
729
|
+
|
730
|
+
```bash
|
731
|
+
$ bin/rake db:rollback
|
732
|
+
```
|
733
|
+
|
734
|
+
This will rollback the latest migration, either by reverting the `change`
|
735
|
+
method or by running the `down` method. If you need to undo
|
736
|
+
several migrations you can provide a `STEP` parameter:
|
737
|
+
|
738
|
+
```bash
|
739
|
+
$ bin/rake db:rollback STEP=3
|
740
|
+
```
|
741
|
+
|
742
|
+
will revert the last 3 migrations.
|
743
|
+
|
744
|
+
The `db:migrate:redo` task is a shortcut for doing a rollback and then migrating
|
745
|
+
back up again. As with the `db:rollback` task, you can use the `STEP` parameter
|
746
|
+
if you need to go more than one version back, for example:
|
747
|
+
|
748
|
+
```bash
|
749
|
+
$ bin/rake db:migrate:redo STEP=3
|
750
|
+
```
|
751
|
+
|
752
|
+
Neither of these Rake tasks do anything you could not do with `db:migrate`. They
|
753
|
+
are simply more convenient, since you do not need to explicitly specify the
|
754
|
+
version to migrate to.
|
755
|
+
|
756
|
+
### Setup the Database
|
757
|
+
|
758
|
+
The `rake db:setup` task will create the database, load the schema and initialize
|
759
|
+
it with the seed data.
|
760
|
+
|
761
|
+
### Resetting the Database
|
762
|
+
|
763
|
+
The `rake db:reset` task will drop the database and set it up again. This is
|
764
|
+
functionally equivalent to `rake db:drop db:setup`.
|
765
|
+
|
766
|
+
NOTE: This is not the same as running all the migrations. It will only use the
|
767
|
+
contents of the current `schema.rb` file. If a migration can't be rolled back,
|
768
|
+
`rake db:reset` may not help you. To find out more about dumping the schema see
|
769
|
+
[Schema Dumping and You](#schema-dumping-and-you) section.
|
770
|
+
|
771
|
+
### Running Specific Migrations
|
772
|
+
|
773
|
+
If you need to run a specific migration up or down, the `db:migrate:up` and
|
774
|
+
`db:migrate:down` tasks will do that. Just specify the appropriate version and
|
775
|
+
the corresponding migration will have its `change`, `up` or `down` method
|
776
|
+
invoked, for example:
|
777
|
+
|
778
|
+
```bash
|
779
|
+
$ bin/rake db:migrate:up VERSION=20080906120000
|
780
|
+
```
|
781
|
+
|
782
|
+
will run the 20080906120000 migration by running the `change` method (or the
|
783
|
+
`up` method). This task will
|
784
|
+
first check whether the migration is already performed and will do nothing if
|
785
|
+
Active Record believes that it has already been run.
|
786
|
+
|
787
|
+
### Running Migrations in Different Environments
|
788
|
+
|
789
|
+
By default running `rake db:migrate` will run in the `development` environment.
|
790
|
+
To run migrations against another environment you can specify it using the
|
791
|
+
`RAILS_ENV` environment variable while running the command. For example to run
|
792
|
+
migrations against the `test` environment you could run:
|
793
|
+
|
794
|
+
```bash
|
795
|
+
$ bin/rake db:migrate RAILS_ENV=test
|
796
|
+
```
|
797
|
+
|
798
|
+
### Changing the Output of Running Migrations
|
799
|
+
|
800
|
+
By default migrations tell you exactly what they're doing and how long it took.
|
801
|
+
A migration creating a table and adding an index might produce output like this
|
802
|
+
|
803
|
+
```bash
|
804
|
+
== CreateProducts: migrating =================================================
|
805
|
+
-- create_table(:products)
|
806
|
+
-> 0.0028s
|
807
|
+
== CreateProducts: migrated (0.0028s) ========================================
|
808
|
+
```
|
809
|
+
|
810
|
+
Several methods are provided in migrations that allow you to control all this:
|
811
|
+
|
812
|
+
| Method | Purpose
|
813
|
+
| -------------------- | -------
|
814
|
+
| suppress_messages | Takes a block as an argument and suppresses any output generated by the block.
|
815
|
+
| say | Takes a message argument and outputs it as is. A second boolean argument can be passed to specify whether to indent or not.
|
816
|
+
| say_with_time | Outputs text along with how long it took to run its block. If the block returns an integer it assumes it is the number of rows affected.
|
817
|
+
|
818
|
+
For example, this migration:
|
819
|
+
|
820
|
+
```ruby
|
821
|
+
class CreateProducts < ActiveRecord::Migration
|
822
|
+
def change
|
823
|
+
suppress_messages do
|
824
|
+
create_table :products do |t|
|
825
|
+
t.string :name
|
826
|
+
t.text :description
|
827
|
+
t.timestamps
|
828
|
+
end
|
829
|
+
end
|
830
|
+
|
831
|
+
say "Created a table"
|
832
|
+
|
833
|
+
suppress_messages {add_index :products, :name}
|
834
|
+
say "and an index!", true
|
835
|
+
|
836
|
+
say_with_time 'Waiting for a while' do
|
837
|
+
sleep 10
|
838
|
+
250
|
839
|
+
end
|
840
|
+
end
|
841
|
+
end
|
842
|
+
```
|
843
|
+
|
844
|
+
generates the following output
|
845
|
+
|
846
|
+
```bash
|
847
|
+
== CreateProducts: migrating =================================================
|
848
|
+
-- Created a table
|
849
|
+
-> and an index!
|
850
|
+
-- Waiting for a while
|
851
|
+
-> 10.0013s
|
852
|
+
-> 250 rows
|
853
|
+
== CreateProducts: migrated (10.0054s) =======================================
|
854
|
+
```
|
855
|
+
|
856
|
+
If you want Active Record to not output anything, then running `rake db:migrate
|
857
|
+
VERBOSE=false` will suppress all output.
|
858
|
+
|
859
|
+
Changing Existing Migrations
|
860
|
+
----------------------------
|
861
|
+
|
862
|
+
Occasionally you will make a mistake when writing a migration. If you have
|
863
|
+
already run the migration then you cannot just edit the migration and run the
|
864
|
+
migration again: Rails thinks it has already run the migration and so will do
|
865
|
+
nothing when you run `rake db:migrate`. You must rollback the migration (for
|
866
|
+
example with `rake db:rollback`), edit your migration and then run
|
867
|
+
`rake db:migrate` to run the corrected version.
|
868
|
+
|
869
|
+
In general, editing existing migrations is not a good idea. You will be
|
870
|
+
creating extra work for yourself and your co-workers and cause major headaches
|
871
|
+
if the existing version of the migration has already been run on production
|
872
|
+
machines. Instead, you should write a new migration that performs the changes
|
873
|
+
you require. Editing a freshly generated migration that has not yet been
|
874
|
+
committed to source control (or, more generally, which has not been propagated
|
875
|
+
beyond your development machine) is relatively harmless.
|
876
|
+
|
877
|
+
The `revert` method can be helpful when writing a new migration to undo
|
878
|
+
previous migrations in whole or in part
|
879
|
+
(see [Reverting Previous Migrations](#reverting-previous-migrations) above).
|
880
|
+
|
881
|
+
Schema Dumping and You
|
882
|
+
----------------------
|
883
|
+
|
884
|
+
### What are Schema Files for?
|
885
|
+
|
886
|
+
Migrations, mighty as they may be, are not the authoritative source for your
|
887
|
+
database schema. That role falls to either `db/schema.rb` or an SQL file which
|
888
|
+
Active Record generates by examining the database. They are not designed to be
|
889
|
+
edited, they just represent the current state of the database.
|
890
|
+
|
891
|
+
There is no need (and it is error prone) to deploy a new instance of an app by
|
892
|
+
replaying the entire migration history. It is much simpler and faster to just
|
893
|
+
load into the database a description of the current schema.
|
894
|
+
|
895
|
+
For example, this is how the test database is created: the current development
|
896
|
+
database is dumped (either to `db/schema.rb` or `db/structure.sql`) and then
|
897
|
+
loaded into the test database.
|
898
|
+
|
899
|
+
Schema files are also useful if you want a quick look at what attributes an
|
900
|
+
Active Record object has. This information is not in the model's code and is
|
901
|
+
frequently spread across several migrations, but the information is nicely
|
902
|
+
summed up in the schema file. The
|
903
|
+
[annotate_models](https://github.com/ctran/annotate_models) gem automatically
|
904
|
+
adds and updates comments at the top of each model summarizing the schema if
|
905
|
+
you desire that functionality.
|
906
|
+
|
907
|
+
### Types of Schema Dumps
|
908
|
+
|
909
|
+
There are two ways to dump the schema. This is set in `config/application.rb`
|
910
|
+
by the `config.active_record.schema_format` setting, which may be either `:sql`
|
911
|
+
or `:ruby`.
|
912
|
+
|
913
|
+
If `:ruby` is selected then the schema is stored in `db/schema.rb`. If you look
|
914
|
+
at this file you'll find that it looks an awful lot like one very big
|
915
|
+
migration:
|
916
|
+
|
917
|
+
```ruby
|
918
|
+
ActiveRecord::Schema.define(version: 20080906171750) do
|
919
|
+
create_table "authors", force: true do |t|
|
920
|
+
t.string "name"
|
921
|
+
t.datetime "created_at"
|
922
|
+
t.datetime "updated_at"
|
923
|
+
end
|
924
|
+
|
925
|
+
create_table "products", force: true do |t|
|
926
|
+
t.string "name"
|
927
|
+
t.text "description"
|
928
|
+
t.datetime "created_at"
|
929
|
+
t.datetime "updated_at"
|
930
|
+
t.string "part_number"
|
931
|
+
end
|
932
|
+
end
|
933
|
+
```
|
934
|
+
|
935
|
+
In many ways this is exactly what it is. This file is created by inspecting the
|
936
|
+
database and expressing its structure using `create_table`, `add_index`, and so
|
937
|
+
on. Because this is database-independent, it could be loaded into any database
|
938
|
+
that Active Record supports. This could be very useful if you were to
|
939
|
+
distribute an application that is able to run against multiple databases.
|
940
|
+
|
941
|
+
There is however a trade-off: `db/schema.rb` cannot express database specific
|
942
|
+
items such as triggers, or stored procedures. While in a migration you can
|
943
|
+
execute custom SQL statements, the schema dumper cannot reconstitute those
|
944
|
+
statements from the database. If you are using features like this, then you
|
945
|
+
should set the schema format to `:sql`.
|
946
|
+
|
947
|
+
Instead of using Active Record's schema dumper, the database's structure will
|
948
|
+
be dumped using a tool specific to the database (via the `db:structure:dump`
|
949
|
+
Rake task) into `db/structure.sql`. For example, for PostgreSQL, the `pg_dump`
|
950
|
+
utility is used. For MySQL, this file will contain the output of
|
951
|
+
`SHOW CREATE TABLE` for the various tables.
|
952
|
+
|
953
|
+
Loading these schemas is simply a question of executing the SQL statements they
|
954
|
+
contain. By definition, this will create a perfect copy of the database's
|
955
|
+
structure. Using the `:sql` schema format will, however, prevent loading the
|
956
|
+
schema into a RDBMS other than the one used to create it.
|
957
|
+
|
958
|
+
### Schema Dumps and Source Control
|
959
|
+
|
960
|
+
Because schema dumps are the authoritative source for your database schema, it
|
961
|
+
is strongly recommended that you check them into source control.
|
962
|
+
|
963
|
+
`db/schema.rb` contains the current version number of the database. This
|
964
|
+
ensures conflicts are going to happen in the case of a merge where both
|
965
|
+
branches touched the schema. When that happens, solve conflicts manually,
|
966
|
+
keeping the highest version number of the two.
|
967
|
+
|
968
|
+
Active Record and Referential Integrity
|
969
|
+
---------------------------------------
|
970
|
+
|
971
|
+
The Active Record way claims that intelligence belongs in your models, not in
|
972
|
+
the database. As such, features such as triggers or constraints,
|
973
|
+
which push some of that intelligence back into the database, are not heavily
|
974
|
+
used.
|
975
|
+
|
976
|
+
Validations such as `validates :foreign_key, uniqueness: true` are one way in
|
977
|
+
which models can enforce data integrity. The `:dependent` option on
|
978
|
+
associations allows models to automatically destroy child objects when the
|
979
|
+
parent is destroyed. Like anything which operates at the application level,
|
980
|
+
these cannot guarantee referential integrity and so some people augment them
|
981
|
+
with [foreign key constraints](#foreign-keys) in the database.
|
982
|
+
|
983
|
+
Although Active Record does not provide all the tools for working directly with
|
984
|
+
such features, the `execute` method can be used to execute arbitrary SQL.
|
985
|
+
|
986
|
+
Migrations and Seed Data
|
987
|
+
------------------------
|
988
|
+
|
989
|
+
Some people use migrations to add data to the database:
|
990
|
+
|
991
|
+
```ruby
|
992
|
+
class AddInitialProducts < ActiveRecord::Migration
|
993
|
+
def up
|
994
|
+
5.times do |i|
|
995
|
+
Product.create(name: "Product ##{i}", description: "A product.")
|
996
|
+
end
|
997
|
+
end
|
998
|
+
|
999
|
+
def down
|
1000
|
+
Product.delete_all
|
1001
|
+
end
|
1002
|
+
end
|
1003
|
+
```
|
1004
|
+
|
1005
|
+
However, Rails has a 'seeds' feature that should be used for seeding a database
|
1006
|
+
with initial data. It's a really simple feature: just fill up `db/seeds.rb`
|
1007
|
+
with some Ruby code, and run `rake db:seed`:
|
1008
|
+
|
1009
|
+
```ruby
|
1010
|
+
5.times do |i|
|
1011
|
+
Product.create(name: "Product ##{i}", description: "A product.")
|
1012
|
+
end
|
1013
|
+
```
|
1014
|
+
|
1015
|
+
This is generally a much cleaner way to set up the database of a blank
|
1016
|
+
application.
|