rails 3.2.22.5 → 4.2.11.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (218) hide show
  1. checksums.yaml +5 -5
  2. data/README.md +85 -0
  3. data/guides/CHANGELOG.md +103 -0
  4. data/guides/Rakefile +92 -0
  5. data/guides/assets/images/akshaysurve.jpg +0 -0
  6. data/guides/assets/images/belongs_to.png +0 -0
  7. data/guides/assets/images/book_icon.gif +0 -0
  8. data/guides/assets/images/bullet.gif +0 -0
  9. data/guides/assets/images/chapters_icon.gif +0 -0
  10. data/guides/assets/images/check_bullet.gif +0 -0
  11. data/guides/assets/images/credits_pic_blank.gif +0 -0
  12. data/guides/assets/images/csrf.png +0 -0
  13. data/guides/assets/images/edge_badge.png +0 -0
  14. data/guides/assets/images/favicon.ico +0 -0
  15. data/guides/assets/images/feature_tile.gif +0 -0
  16. data/guides/assets/images/footer_tile.gif +0 -0
  17. data/guides/assets/images/fxn.png +0 -0
  18. data/guides/assets/images/getting_started/article_with_comments.png +0 -0
  19. data/guides/assets/images/getting_started/challenge.png +0 -0
  20. data/guides/assets/images/getting_started/confirm_dialog.png +0 -0
  21. data/guides/assets/images/getting_started/forbidden_attributes_for_new_article.png +0 -0
  22. data/guides/assets/images/getting_started/form_with_errors.png +0 -0
  23. data/guides/assets/images/getting_started/index_action_with_edit_link.png +0 -0
  24. data/guides/assets/images/getting_started/new_article.png +0 -0
  25. data/guides/assets/images/getting_started/rails_welcome.png +0 -0
  26. data/guides/assets/images/getting_started/routing_error_no_controller.png +0 -0
  27. data/guides/assets/images/getting_started/routing_error_no_route_matches.png +0 -0
  28. data/guides/assets/images/getting_started/show_action_for_articles.png +0 -0
  29. data/guides/assets/images/getting_started/template_is_missing_articles_new.png +0 -0
  30. data/guides/assets/images/getting_started/unknown_action_create_for_articles.png +0 -0
  31. data/guides/assets/images/getting_started/unknown_action_new_for_articles.png +0 -0
  32. data/guides/assets/images/grey_bullet.gif +0 -0
  33. data/guides/assets/images/habtm.png +0 -0
  34. data/guides/assets/images/has_many.png +0 -0
  35. data/guides/assets/images/has_many_through.png +0 -0
  36. data/guides/assets/images/has_one.png +0 -0
  37. data/guides/assets/images/has_one_through.png +0 -0
  38. data/guides/assets/images/header_backdrop.png +0 -0
  39. data/guides/assets/images/header_tile.gif +0 -0
  40. data/guides/assets/images/i18n/demo_html_safe.png +0 -0
  41. data/guides/assets/images/i18n/demo_localized_pirate.png +0 -0
  42. data/guides/assets/images/i18n/demo_translated_en.png +0 -0
  43. data/guides/assets/images/i18n/demo_translated_pirate.png +0 -0
  44. data/guides/assets/images/i18n/demo_translation_missing.png +0 -0
  45. data/guides/assets/images/i18n/demo_untranslated.png +0 -0
  46. data/guides/assets/images/icons/README +5 -0
  47. data/guides/assets/images/icons/callouts/1.png +0 -0
  48. data/guides/assets/images/icons/callouts/10.png +0 -0
  49. data/guides/assets/images/icons/callouts/11.png +0 -0
  50. data/guides/assets/images/icons/callouts/12.png +0 -0
  51. data/guides/assets/images/icons/callouts/13.png +0 -0
  52. data/guides/assets/images/icons/callouts/14.png +0 -0
  53. data/guides/assets/images/icons/callouts/15.png +0 -0
  54. data/guides/assets/images/icons/callouts/2.png +0 -0
  55. data/guides/assets/images/icons/callouts/3.png +0 -0
  56. data/guides/assets/images/icons/callouts/4.png +0 -0
  57. data/guides/assets/images/icons/callouts/5.png +0 -0
  58. data/guides/assets/images/icons/callouts/6.png +0 -0
  59. data/guides/assets/images/icons/callouts/7.png +0 -0
  60. data/guides/assets/images/icons/callouts/8.png +0 -0
  61. data/guides/assets/images/icons/callouts/9.png +0 -0
  62. data/guides/assets/images/icons/caution.png +0 -0
  63. data/guides/assets/images/icons/example.png +0 -0
  64. data/guides/assets/images/icons/home.png +0 -0
  65. data/guides/assets/images/icons/important.png +0 -0
  66. data/guides/assets/images/icons/next.png +0 -0
  67. data/guides/assets/images/icons/note.png +0 -0
  68. data/guides/assets/images/icons/prev.png +0 -0
  69. data/guides/assets/images/icons/tip.png +0 -0
  70. data/guides/assets/images/icons/up.png +0 -0
  71. data/guides/assets/images/icons/warning.png +0 -0
  72. data/guides/assets/images/nav_arrow.gif +0 -0
  73. data/guides/assets/images/oscardelben.jpg +0 -0
  74. data/guides/assets/images/polymorphic.png +0 -0
  75. data/guides/assets/images/radar.png +0 -0
  76. data/guides/assets/images/rails4_features.png +0 -0
  77. data/guides/assets/images/rails_guides_kindle_cover.jpg +0 -0
  78. data/guides/assets/images/rails_guides_logo.gif +0 -0
  79. data/guides/assets/images/rails_logo_remix.gif +0 -0
  80. data/guides/assets/images/session_fixation.png +0 -0
  81. data/guides/assets/images/tab_grey.gif +0 -0
  82. data/guides/assets/images/tab_info.gif +0 -0
  83. data/guides/assets/images/tab_note.gif +0 -0
  84. data/guides/assets/images/tab_red.gif +0 -0
  85. data/guides/assets/images/tab_yellow.gif +0 -0
  86. data/guides/assets/images/tab_yellow.png +0 -0
  87. data/guides/assets/images/vijaydev.jpg +0 -0
  88. data/guides/assets/javascripts/guides.js +59 -0
  89. data/guides/assets/javascripts/jquery.min.js +4 -0
  90. data/guides/assets/javascripts/responsive-tables.js +43 -0
  91. data/guides/assets/javascripts/syntaxhighlighter/shBrushAS3.js +59 -0
  92. data/guides/assets/javascripts/syntaxhighlighter/shBrushAppleScript.js +75 -0
  93. data/guides/assets/javascripts/syntaxhighlighter/shBrushBash.js +59 -0
  94. data/guides/assets/javascripts/syntaxhighlighter/shBrushCSharp.js +65 -0
  95. data/guides/assets/javascripts/syntaxhighlighter/shBrushColdFusion.js +100 -0
  96. data/guides/assets/javascripts/syntaxhighlighter/shBrushCpp.js +97 -0
  97. data/guides/assets/javascripts/syntaxhighlighter/shBrushCss.js +91 -0
  98. data/guides/assets/javascripts/syntaxhighlighter/shBrushDelphi.js +55 -0
  99. data/guides/assets/javascripts/syntaxhighlighter/shBrushDiff.js +41 -0
  100. data/guides/assets/javascripts/syntaxhighlighter/shBrushErlang.js +52 -0
  101. data/guides/assets/javascripts/syntaxhighlighter/shBrushGroovy.js +67 -0
  102. data/guides/assets/javascripts/syntaxhighlighter/shBrushJScript.js +52 -0
  103. data/guides/assets/javascripts/syntaxhighlighter/shBrushJava.js +57 -0
  104. data/guides/assets/javascripts/syntaxhighlighter/shBrushJavaFX.js +58 -0
  105. data/guides/assets/javascripts/syntaxhighlighter/shBrushPerl.js +72 -0
  106. data/guides/assets/javascripts/syntaxhighlighter/shBrushPhp.js +88 -0
  107. data/guides/assets/javascripts/syntaxhighlighter/shBrushPlain.js +33 -0
  108. data/guides/assets/javascripts/syntaxhighlighter/shBrushPowerShell.js +74 -0
  109. data/guides/assets/javascripts/syntaxhighlighter/shBrushPython.js +64 -0
  110. data/guides/assets/javascripts/syntaxhighlighter/shBrushRuby.js +55 -0
  111. data/guides/assets/javascripts/syntaxhighlighter/shBrushSass.js +94 -0
  112. data/guides/assets/javascripts/syntaxhighlighter/shBrushScala.js +51 -0
  113. data/guides/assets/javascripts/syntaxhighlighter/shBrushSql.js +66 -0
  114. data/guides/assets/javascripts/syntaxhighlighter/shBrushVb.js +56 -0
  115. data/guides/assets/javascripts/syntaxhighlighter/shBrushXml.js +69 -0
  116. data/guides/assets/javascripts/syntaxhighlighter/shCore.js +17 -0
  117. data/guides/assets/stylesheets/fixes.css +16 -0
  118. data/guides/assets/stylesheets/kindle.css +11 -0
  119. data/guides/assets/stylesheets/main.css +713 -0
  120. data/guides/assets/stylesheets/print.css +52 -0
  121. data/guides/assets/stylesheets/reset.css +43 -0
  122. data/guides/assets/stylesheets/responsive-tables.css +50 -0
  123. data/guides/assets/stylesheets/style.css +13 -0
  124. data/guides/assets/stylesheets/syntaxhighlighter/shCore.css +226 -0
  125. data/guides/assets/stylesheets/syntaxhighlighter/shCoreDefault.css +328 -0
  126. data/guides/assets/stylesheets/syntaxhighlighter/shCoreDjango.css +331 -0
  127. data/guides/assets/stylesheets/syntaxhighlighter/shCoreEclipse.css +339 -0
  128. data/guides/assets/stylesheets/syntaxhighlighter/shCoreEmacs.css +324 -0
  129. data/guides/assets/stylesheets/syntaxhighlighter/shCoreFadeToGrey.css +328 -0
  130. data/guides/assets/stylesheets/syntaxhighlighter/shCoreMDUltra.css +324 -0
  131. data/guides/assets/stylesheets/syntaxhighlighter/shCoreMidnight.css +324 -0
  132. data/guides/assets/stylesheets/syntaxhighlighter/shCoreRDark.css +324 -0
  133. data/guides/assets/stylesheets/syntaxhighlighter/shThemeDefault.css +117 -0
  134. data/guides/assets/stylesheets/syntaxhighlighter/shThemeDjango.css +120 -0
  135. data/guides/assets/stylesheets/syntaxhighlighter/shThemeEclipse.css +128 -0
  136. data/guides/assets/stylesheets/syntaxhighlighter/shThemeEmacs.css +113 -0
  137. data/guides/assets/stylesheets/syntaxhighlighter/shThemeFadeToGrey.css +117 -0
  138. data/guides/assets/stylesheets/syntaxhighlighter/shThemeMDUltra.css +113 -0
  139. data/guides/assets/stylesheets/syntaxhighlighter/shThemeMidnight.css +113 -0
  140. data/guides/assets/stylesheets/syntaxhighlighter/shThemeRDark.css +113 -0
  141. data/guides/assets/stylesheets/syntaxhighlighter/shThemeRailsGuides.css +116 -0
  142. data/guides/bug_report_templates/action_controller_gem.rb +47 -0
  143. data/guides/bug_report_templates/action_controller_master.rb +54 -0
  144. data/guides/bug_report_templates/active_record_gem.rb +40 -0
  145. data/guides/bug_report_templates/active_record_master.rb +49 -0
  146. data/guides/bug_report_templates/generic_gem.rb +15 -0
  147. data/guides/bug_report_templates/generic_master.rb +26 -0
  148. data/guides/rails_guides.rb +63 -0
  149. data/guides/rails_guides/generator.rb +248 -0
  150. data/guides/rails_guides/helpers.rb +53 -0
  151. data/guides/rails_guides/indexer.rb +68 -0
  152. data/guides/rails_guides/kindle.rb +119 -0
  153. data/guides/rails_guides/levenshtein.rb +37 -0
  154. data/guides/rails_guides/markdown.rb +167 -0
  155. data/guides/rails_guides/markdown/renderer.rb +82 -0
  156. data/guides/source/2_2_release_notes.md +435 -0
  157. data/guides/source/2_3_release_notes.md +621 -0
  158. data/guides/source/3_0_release_notes.md +611 -0
  159. data/guides/source/3_1_release_notes.md +559 -0
  160. data/guides/source/3_2_release_notes.md +568 -0
  161. data/guides/source/4_0_release_notes.md +279 -0
  162. data/guides/source/4_1_release_notes.md +730 -0
  163. data/guides/source/4_2_release_notes.md +877 -0
  164. data/guides/source/_license.html.erb +2 -0
  165. data/guides/source/_welcome.html.erb +23 -0
  166. data/guides/source/action_controller_overview.md +1192 -0
  167. data/guides/source/action_mailer_basics.md +757 -0
  168. data/guides/source/action_view_overview.md +1561 -0
  169. data/guides/source/active_job_basics.md +339 -0
  170. data/guides/source/active_model_basics.md +554 -0
  171. data/guides/source/active_record_basics.md +374 -0
  172. data/guides/source/active_record_callbacks.md +413 -0
  173. data/guides/source/active_record_migrations.md +1018 -0
  174. data/guides/source/active_record_postgresql.md +433 -0
  175. data/guides/source/active_record_querying.md +1781 -0
  176. data/guides/source/active_record_validations.md +1179 -0
  177. data/guides/source/active_support_core_extensions.md +3856 -0
  178. data/guides/source/active_support_instrumentation.md +488 -0
  179. data/guides/source/api_documentation_guidelines.md +361 -0
  180. data/guides/source/asset_pipeline.md +1304 -0
  181. data/guides/source/association_basics.md +2245 -0
  182. data/guides/source/autoloading_and_reloading_constants.md +1311 -0
  183. data/guides/source/caching_with_rails.md +379 -0
  184. data/guides/source/command_line.md +625 -0
  185. data/guides/source/configuring.md +1070 -0
  186. data/guides/source/contributing_to_ruby_on_rails.md +628 -0
  187. data/guides/source/credits.html.erb +80 -0
  188. data/guides/source/debugging_rails_applications.md +861 -0
  189. data/guides/source/development_dependencies_install.md +289 -0
  190. data/guides/source/documents.yaml +205 -0
  191. data/guides/source/engines.md +1412 -0
  192. data/guides/source/form_helpers.md +1024 -0
  193. data/guides/source/generators.md +676 -0
  194. data/guides/source/getting_started.md +2086 -0
  195. data/guides/source/i18n.md +1087 -0
  196. data/guides/source/index.html.erb +28 -0
  197. data/guides/source/initialization.md +704 -0
  198. data/guides/source/kindle/copyright.html.erb +1 -0
  199. data/guides/source/kindle/layout.html.erb +27 -0
  200. data/guides/source/kindle/rails_guides.opf.erb +52 -0
  201. data/guides/source/kindle/toc.html.erb +24 -0
  202. data/guides/source/kindle/toc.ncx.erb +64 -0
  203. data/guides/source/kindle/welcome.html.erb +5 -0
  204. data/guides/source/layout.html.erb +140 -0
  205. data/guides/source/layouts_and_rendering.md +1226 -0
  206. data/guides/source/maintenance_policy.md +78 -0
  207. data/guides/source/nested_model_forms.md +228 -0
  208. data/guides/source/plugins.md +444 -0
  209. data/guides/source/rails_application_templates.md +266 -0
  210. data/guides/source/rails_on_rack.md +335 -0
  211. data/guides/source/routing.md +1155 -0
  212. data/guides/source/ruby_on_rails_guides_guidelines.md +127 -0
  213. data/guides/source/security.md +1024 -0
  214. data/guides/source/testing.md +1132 -0
  215. data/guides/source/upgrading_ruby_on_rails.md +1186 -0
  216. data/guides/source/working_with_javascript_in_rails.md +407 -0
  217. data/guides/w3c_validator.rb +97 -0
  218. metadata +288 -26
@@ -0,0 +1,1018 @@
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 null: false
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 null: false
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
+ * `required` Adds `required: true` for `belongs_to` associations and
456
+ `null: false` to the column in the migration.
457
+
458
+ Some adapters may support additional options; see the adapter specific API docs
459
+ for further information.
460
+
461
+ ### Foreign Keys
462
+
463
+ While it's not required you might want to add foreign key constraints to
464
+ [guarantee referential integrity](#active-record-and-referential-integrity).
465
+
466
+ ```ruby
467
+ add_foreign_key :articles, :authors
468
+ ```
469
+
470
+ This adds a new foreign key to the `author_id` column of the `articles`
471
+ table. The key references the `id` column of the `authors` table. If the
472
+ column names can not be derived from the table names, you can use the
473
+ `:column` and `:primary_key` options.
474
+
475
+ Rails will generate a name for every foreign key starting with
476
+ `fk_rails_` followed by 10 random characters.
477
+ There is a `:name` option to specify a different name if needed.
478
+
479
+ NOTE: Active Record only supports single column foreign keys. `execute` and
480
+ `structure.sql` are required to use composite foreign keys.
481
+
482
+ Removing a foreign key is easy as well:
483
+
484
+ ```ruby
485
+ # let Active Record figure out the column name
486
+ remove_foreign_key :accounts, :branches
487
+
488
+ # remove foreign key for a specific column
489
+ remove_foreign_key :accounts, column: :owner_id
490
+
491
+ # remove foreign key by name
492
+ remove_foreign_key :accounts, name: :special_fk_name
493
+ ```
494
+
495
+ ### When Helpers aren't Enough
496
+
497
+ If the helpers provided by Active Record aren't enough you can use the `execute`
498
+ method to execute arbitrary SQL:
499
+
500
+ ```ruby
501
+ Product.connection.execute('UPDATE `products` SET `price`=`free` WHERE 1')
502
+ ```
503
+
504
+ For more details and examples of individual methods, check the API documentation.
505
+ In particular the documentation for
506
+ [`ActiveRecord::ConnectionAdapters::SchemaStatements`](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html)
507
+ (which provides the methods available in the `change`, `up` and `down` methods),
508
+ [`ActiveRecord::ConnectionAdapters::TableDefinition`](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html)
509
+ (which provides the methods available on the object yielded by `create_table`)
510
+ and
511
+ [`ActiveRecord::ConnectionAdapters::Table`](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html)
512
+ (which provides the methods available on the object yielded by `change_table`).
513
+
514
+ ### Using the `change` Method
515
+
516
+ The `change` method is the primary way of writing migrations. It works for the
517
+ majority of cases, where Active Record knows how to reverse the migration
518
+ automatically. Currently, the `change` method supports only these migration
519
+ definitions:
520
+
521
+ * `add_column`
522
+ * `add_index`
523
+ * `add_reference`
524
+ * `add_timestamps`
525
+ * `add_foreign_key`
526
+ * `create_table`
527
+ * `create_join_table`
528
+ * `drop_table` (must supply a block)
529
+ * `drop_join_table` (must supply a block)
530
+ * `remove_timestamps`
531
+ * `rename_column`
532
+ * `rename_index`
533
+ * `remove_reference`
534
+ * `rename_table`
535
+
536
+ `change_table` is also reversible, as long as the block does not call `change`,
537
+ `change_default` or `remove`.
538
+
539
+ If you're going to need to use any other methods, you should use `reversible`
540
+ or write the `up` and `down` methods instead of using the `change` method.
541
+
542
+ ### Using `reversible`
543
+
544
+ Complex migrations may require processing that Active Record doesn't know how
545
+ to reverse. You can use `reversible` to specify what to do when running a
546
+ migration what else to do when reverting it. For example:
547
+
548
+ ```ruby
549
+ class ExampleMigration < ActiveRecord::Migration
550
+ def change
551
+ create_table :distributors do |t|
552
+ t.string :zipcode
553
+ end
554
+
555
+ reversible do |dir|
556
+ dir.up do
557
+ # add a CHECK constraint
558
+ execute <<-SQL
559
+ ALTER TABLE distributors
560
+ ADD CONSTRAINT zipchk
561
+ CHECK (char_length(zipcode) = 5) NO INHERIT;
562
+ SQL
563
+ end
564
+ dir.down do
565
+ execute <<-SQL
566
+ ALTER TABLE distributors
567
+ DROP CONSTRAINT zipchk
568
+ SQL
569
+ end
570
+ end
571
+
572
+ add_column :users, :home_page_url, :string
573
+ rename_column :users, :email, :email_address
574
+ end
575
+ end
576
+ ```
577
+
578
+ Using `reversible` will ensure that the instructions are executed in the
579
+ right order too. If the previous example migration is reverted,
580
+ the `down` block will be run after the `home_page_url` column is removed and
581
+ right before the table `distributors` is dropped.
582
+
583
+ Sometimes your migration will do something which is just plain irreversible; for
584
+ example, it might destroy some data. In such cases, you can raise
585
+ `ActiveRecord::IrreversibleMigration` in your `down` block. If someone tries
586
+ to revert your migration, an error message will be displayed saying that it
587
+ can't be done.
588
+
589
+ ### Using the `up`/`down` Methods
590
+
591
+ You can also use the old style of migration using `up` and `down` methods
592
+ instead of the `change` method.
593
+ The `up` method should describe the transformation you'd like to make to your
594
+ schema, and the `down` method of your migration should revert the
595
+ transformations done by the `up` method. In other words, the database schema
596
+ should be unchanged if you do an `up` followed by a `down`. For example, if you
597
+ create a table in the `up` method, you should drop it in the `down` method. It
598
+ is wise to reverse the transformations in precisely the reverse order they were
599
+ made in the `up` method. The example in the `reversible` section is equivalent to:
600
+
601
+ ```ruby
602
+ class ExampleMigration < ActiveRecord::Migration
603
+ def up
604
+ create_table :distributors do |t|
605
+ t.string :zipcode
606
+ end
607
+
608
+ # add a CHECK constraint
609
+ execute <<-SQL
610
+ ALTER TABLE distributors
611
+ ADD CONSTRAINT zipchk
612
+ CHECK (char_length(zipcode) = 5);
613
+ SQL
614
+
615
+ add_column :users, :home_page_url, :string
616
+ rename_column :users, :email, :email_address
617
+ end
618
+
619
+ def down
620
+ rename_column :users, :email_address, :email
621
+ remove_column :users, :home_page_url
622
+
623
+ execute <<-SQL
624
+ ALTER TABLE distributors
625
+ DROP CONSTRAINT zipchk
626
+ SQL
627
+
628
+ drop_table :distributors
629
+ end
630
+ end
631
+ ```
632
+
633
+ If your migration is irreversible, you should raise
634
+ `ActiveRecord::IrreversibleMigration` from your `down` method. If someone tries
635
+ to revert your migration, an error message will be displayed saying that it
636
+ can't be done.
637
+
638
+ ### Reverting Previous Migrations
639
+
640
+ You can use Active Record's ability to rollback migrations using the `revert` method:
641
+
642
+ ```ruby
643
+ require_relative '2012121212_example_migration'
644
+
645
+ class FixupExampleMigration < ActiveRecord::Migration
646
+ def change
647
+ revert ExampleMigration
648
+
649
+ create_table(:apples) do |t|
650
+ t.string :variety
651
+ end
652
+ end
653
+ end
654
+ ```
655
+
656
+ The `revert` method also accepts a block of instructions to reverse.
657
+ This could be useful to revert selected parts of previous migrations.
658
+ For example, let's imagine that `ExampleMigration` is committed and it
659
+ is later decided it would be best to use Active Record validations,
660
+ in place of the `CHECK` constraint, to verify the zipcode.
661
+
662
+ ```ruby
663
+ class DontUseConstraintForZipcodeValidationMigration < ActiveRecord::Migration
664
+ def change
665
+ revert do
666
+ # copy-pasted code from ExampleMigration
667
+ reversible do |dir|
668
+ dir.up do
669
+ # add a CHECK constraint
670
+ execute <<-SQL
671
+ ALTER TABLE distributors
672
+ ADD CONSTRAINT zipchk
673
+ CHECK (char_length(zipcode) = 5);
674
+ SQL
675
+ end
676
+ dir.down do
677
+ execute <<-SQL
678
+ ALTER TABLE distributors
679
+ DROP CONSTRAINT zipchk
680
+ SQL
681
+ end
682
+ end
683
+
684
+ # The rest of the migration was ok
685
+ end
686
+ end
687
+ end
688
+ ```
689
+
690
+ The same migration could also have been written without using `revert`
691
+ but this would have involved a few more steps: reversing the order
692
+ of `create_table` and `reversible`, replacing `create_table`
693
+ by `drop_table`, and finally replacing `up` by `down` and vice-versa.
694
+ This is all taken care of by `revert`.
695
+
696
+ Running Migrations
697
+ ------------------
698
+
699
+ Rails provides a set of Rake tasks to run certain sets of migrations.
700
+
701
+ The very first migration related Rake task you will use will probably be
702
+ `rake db:migrate`. In its most basic form it just runs the `change` or `up`
703
+ method for all the migrations that have not yet been run. If there are
704
+ no such migrations, it exits. It will run these migrations in order based
705
+ on the date of the migration.
706
+
707
+ Note that running the `db:migrate` task also invokes the `db:schema:dump` task, which
708
+ will update your `db/schema.rb` file to match the structure of your database.
709
+
710
+ If you specify a target version, Active Record will run the required migrations
711
+ (change, up, down) until it has reached the specified version. The version
712
+ is the numerical prefix on the migration's filename. For example, to migrate
713
+ to version 20080906120000 run:
714
+
715
+ ```bash
716
+ $ bin/rake db:migrate VERSION=20080906120000
717
+ ```
718
+
719
+ If version 20080906120000 is greater than the current version (i.e., it is
720
+ migrating upwards), this will run the `change` (or `up`) method
721
+ on all migrations up to and
722
+ including 20080906120000, and will not execute any later migrations. If
723
+ migrating downwards, this will run the `down` method on all the migrations
724
+ down to, but not including, 20080906120000.
725
+
726
+ ### Rolling Back
727
+
728
+ A common task is to rollback the last migration. For example, if you made a
729
+ mistake in it and wish to correct it. Rather than tracking down the version
730
+ number associated with the previous migration you can run:
731
+
732
+ ```bash
733
+ $ bin/rake db:rollback
734
+ ```
735
+
736
+ This will rollback the latest migration, either by reverting the `change`
737
+ method or by running the `down` method. If you need to undo
738
+ several migrations you can provide a `STEP` parameter:
739
+
740
+ ```bash
741
+ $ bin/rake db:rollback STEP=3
742
+ ```
743
+
744
+ will revert the last 3 migrations.
745
+
746
+ The `db:migrate:redo` task is a shortcut for doing a rollback and then migrating
747
+ back up again. As with the `db:rollback` task, you can use the `STEP` parameter
748
+ if you need to go more than one version back, for example:
749
+
750
+ ```bash
751
+ $ bin/rake db:migrate:redo STEP=3
752
+ ```
753
+
754
+ Neither of these Rake tasks do anything you could not do with `db:migrate`. They
755
+ are simply more convenient, since you do not need to explicitly specify the
756
+ version to migrate to.
757
+
758
+ ### Setup the Database
759
+
760
+ The `rake db:setup` task will create the database, load the schema and initialize
761
+ it with the seed data.
762
+
763
+ ### Resetting the Database
764
+
765
+ The `rake db:reset` task will drop the database and set it up again. This is
766
+ functionally equivalent to `rake db:drop db:setup`.
767
+
768
+ NOTE: This is not the same as running all the migrations. It will only use the
769
+ contents of the current `schema.rb` file. If a migration can't be rolled back,
770
+ `rake db:reset` may not help you. To find out more about dumping the schema see
771
+ [Schema Dumping and You](#schema-dumping-and-you) section.
772
+
773
+ ### Running Specific Migrations
774
+
775
+ If you need to run a specific migration up or down, the `db:migrate:up` and
776
+ `db:migrate:down` tasks will do that. Just specify the appropriate version and
777
+ the corresponding migration will have its `change`, `up` or `down` method
778
+ invoked, for example:
779
+
780
+ ```bash
781
+ $ bin/rake db:migrate:up VERSION=20080906120000
782
+ ```
783
+
784
+ will run the 20080906120000 migration by running the `change` method (or the
785
+ `up` method). This task will
786
+ first check whether the migration is already performed and will do nothing if
787
+ Active Record believes that it has already been run.
788
+
789
+ ### Running Migrations in Different Environments
790
+
791
+ By default running `rake db:migrate` will run in the `development` environment.
792
+ To run migrations against another environment you can specify it using the
793
+ `RAILS_ENV` environment variable while running the command. For example to run
794
+ migrations against the `test` environment you could run:
795
+
796
+ ```bash
797
+ $ bin/rake db:migrate RAILS_ENV=test
798
+ ```
799
+
800
+ ### Changing the Output of Running Migrations
801
+
802
+ By default migrations tell you exactly what they're doing and how long it took.
803
+ A migration creating a table and adding an index might produce output like this
804
+
805
+ ```bash
806
+ == CreateProducts: migrating =================================================
807
+ -- create_table(:products)
808
+ -> 0.0028s
809
+ == CreateProducts: migrated (0.0028s) ========================================
810
+ ```
811
+
812
+ Several methods are provided in migrations that allow you to control all this:
813
+
814
+ | Method | Purpose
815
+ | -------------------- | -------
816
+ | suppress_messages | Takes a block as an argument and suppresses any output generated by the block.
817
+ | say | Takes a message argument and outputs it as is. A second boolean argument can be passed to specify whether to indent or not.
818
+ | 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.
819
+
820
+ For example, this migration:
821
+
822
+ ```ruby
823
+ class CreateProducts < ActiveRecord::Migration
824
+ def change
825
+ suppress_messages do
826
+ create_table :products do |t|
827
+ t.string :name
828
+ t.text :description
829
+ t.timestamps null: false
830
+ end
831
+ end
832
+
833
+ say "Created a table"
834
+
835
+ suppress_messages {add_index :products, :name}
836
+ say "and an index!", true
837
+
838
+ say_with_time 'Waiting for a while' do
839
+ sleep 10
840
+ 250
841
+ end
842
+ end
843
+ end
844
+ ```
845
+
846
+ generates the following output
847
+
848
+ ```bash
849
+ == CreateProducts: migrating =================================================
850
+ -- Created a table
851
+ -> and an index!
852
+ -- Waiting for a while
853
+ -> 10.0013s
854
+ -> 250 rows
855
+ == CreateProducts: migrated (10.0054s) =======================================
856
+ ```
857
+
858
+ If you want Active Record to not output anything, then running `rake db:migrate
859
+ VERBOSE=false` will suppress all output.
860
+
861
+ Changing Existing Migrations
862
+ ----------------------------
863
+
864
+ Occasionally you will make a mistake when writing a migration. If you have
865
+ already run the migration then you cannot just edit the migration and run the
866
+ migration again: Rails thinks it has already run the migration and so will do
867
+ nothing when you run `rake db:migrate`. You must rollback the migration (for
868
+ example with `rake db:rollback`), edit your migration and then run
869
+ `rake db:migrate` to run the corrected version.
870
+
871
+ In general, editing existing migrations is not a good idea. You will be
872
+ creating extra work for yourself and your co-workers and cause major headaches
873
+ if the existing version of the migration has already been run on production
874
+ machines. Instead, you should write a new migration that performs the changes
875
+ you require. Editing a freshly generated migration that has not yet been
876
+ committed to source control (or, more generally, which has not been propagated
877
+ beyond your development machine) is relatively harmless.
878
+
879
+ The `revert` method can be helpful when writing a new migration to undo
880
+ previous migrations in whole or in part
881
+ (see [Reverting Previous Migrations](#reverting-previous-migrations) above).
882
+
883
+ Schema Dumping and You
884
+ ----------------------
885
+
886
+ ### What are Schema Files for?
887
+
888
+ Migrations, mighty as they may be, are not the authoritative source for your
889
+ database schema. That role falls to either `db/schema.rb` or an SQL file which
890
+ Active Record generates by examining the database. They are not designed to be
891
+ edited, they just represent the current state of the database.
892
+
893
+ There is no need (and it is error prone) to deploy a new instance of an app by
894
+ replaying the entire migration history. It is much simpler and faster to just
895
+ load into the database a description of the current schema.
896
+
897
+ For example, this is how the test database is created: the current development
898
+ database is dumped (either to `db/schema.rb` or `db/structure.sql`) and then
899
+ loaded into the test database.
900
+
901
+ Schema files are also useful if you want a quick look at what attributes an
902
+ Active Record object has. This information is not in the model's code and is
903
+ frequently spread across several migrations, but the information is nicely
904
+ summed up in the schema file. The
905
+ [annotate_models](https://github.com/ctran/annotate_models) gem automatically
906
+ adds and updates comments at the top of each model summarizing the schema if
907
+ you desire that functionality.
908
+
909
+ ### Types of Schema Dumps
910
+
911
+ There are two ways to dump the schema. This is set in `config/application.rb`
912
+ by the `config.active_record.schema_format` setting, which may be either `:sql`
913
+ or `:ruby`.
914
+
915
+ If `:ruby` is selected then the schema is stored in `db/schema.rb`. If you look
916
+ at this file you'll find that it looks an awful lot like one very big
917
+ migration:
918
+
919
+ ```ruby
920
+ ActiveRecord::Schema.define(version: 20080906171750) do
921
+ create_table "authors", force: true do |t|
922
+ t.string "name"
923
+ t.datetime "created_at"
924
+ t.datetime "updated_at"
925
+ end
926
+
927
+ create_table "products", force: true do |t|
928
+ t.string "name"
929
+ t.text "description"
930
+ t.datetime "created_at"
931
+ t.datetime "updated_at"
932
+ t.string "part_number"
933
+ end
934
+ end
935
+ ```
936
+
937
+ In many ways this is exactly what it is. This file is created by inspecting the
938
+ database and expressing its structure using `create_table`, `add_index`, and so
939
+ on. Because this is database-independent, it could be loaded into any database
940
+ that Active Record supports. This could be very useful if you were to
941
+ distribute an application that is able to run against multiple databases.
942
+
943
+ There is however a trade-off: `db/schema.rb` cannot express database specific
944
+ items such as triggers, or stored procedures. While in a migration you can
945
+ execute custom SQL statements, the schema dumper cannot reconstitute those
946
+ statements from the database. If you are using features like this, then you
947
+ should set the schema format to `:sql`.
948
+
949
+ Instead of using Active Record's schema dumper, the database's structure will
950
+ be dumped using a tool specific to the database (via the `db:structure:dump`
951
+ Rake task) into `db/structure.sql`. For example, for PostgreSQL, the `pg_dump`
952
+ utility is used. For MySQL, this file will contain the output of
953
+ `SHOW CREATE TABLE` for the various tables.
954
+
955
+ Loading these schemas is simply a question of executing the SQL statements they
956
+ contain. By definition, this will create a perfect copy of the database's
957
+ structure. Using the `:sql` schema format will, however, prevent loading the
958
+ schema into a RDBMS other than the one used to create it.
959
+
960
+ ### Schema Dumps and Source Control
961
+
962
+ Because schema dumps are the authoritative source for your database schema, it
963
+ is strongly recommended that you check them into source control.
964
+
965
+ `db/schema.rb` contains the current version number of the database. This
966
+ ensures conflicts are going to happen in the case of a merge where both
967
+ branches touched the schema. When that happens, solve conflicts manually,
968
+ keeping the highest version number of the two.
969
+
970
+ Active Record and Referential Integrity
971
+ ---------------------------------------
972
+
973
+ The Active Record way claims that intelligence belongs in your models, not in
974
+ the database. As such, features such as triggers or constraints,
975
+ which push some of that intelligence back into the database, are not heavily
976
+ used.
977
+
978
+ Validations such as `validates :foreign_key, uniqueness: true` are one way in
979
+ which models can enforce data integrity. The `:dependent` option on
980
+ associations allows models to automatically destroy child objects when the
981
+ parent is destroyed. Like anything which operates at the application level,
982
+ these cannot guarantee referential integrity and so some people augment them
983
+ with [foreign key constraints](#foreign-keys) in the database.
984
+
985
+ Although Active Record does not provide all the tools for working directly with
986
+ such features, the `execute` method can be used to execute arbitrary SQL.
987
+
988
+ Migrations and Seed Data
989
+ ------------------------
990
+
991
+ Some people use migrations to add data to the database:
992
+
993
+ ```ruby
994
+ class AddInitialProducts < ActiveRecord::Migration
995
+ def up
996
+ 5.times do |i|
997
+ Product.create(name: "Product ##{i}", description: "A product.")
998
+ end
999
+ end
1000
+
1001
+ def down
1002
+ Product.delete_all
1003
+ end
1004
+ end
1005
+ ```
1006
+
1007
+ However, Rails has a 'seeds' feature that should be used for seeding a database
1008
+ with initial data. It's a really simple feature: just fill up `db/seeds.rb`
1009
+ with some Ruby code, and run `rake db:seed`:
1010
+
1011
+ ```ruby
1012
+ 5.times do |i|
1013
+ Product.create(name: "Product ##{i}", description: "A product.")
1014
+ end
1015
+ ```
1016
+
1017
+ This is generally a much cleaner way to set up the database of a blank
1018
+ application.