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