From 39e1ac658efc80e4c54abef4f1c7679e4b3dc2ac Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sun, 18 Jan 2009 18:10:58 +0000 Subject: Merge docrails --- railties/doc/guides/html/2_2_release_notes.html | 642 +++---- railties/doc/guides/html/action_mailer_basics.html | 197 ++ .../doc/guides/html/actioncontroller_basics.html | 724 +++---- .../doc/guides/html/active_record_querying.html | 932 +++++++++ .../html/activerecord_validations_callbacks.html | 1203 ++++++------ railties/doc/guides/html/association_basics.html | 1195 +++++------- railties/doc/guides/html/authors.html | 248 +-- .../guides/html/benchmarking_and_profiling.html | 1018 ---------- railties/doc/guides/html/caching_with_rails.html | 449 ++--- railties/doc/guides/html/command_line.html | 501 ++--- railties/doc/guides/html/configuring.html | 616 +++--- railties/doc/guides/html/creating_plugins.html | 908 ++++----- .../guides/html/debugging_rails_applications.html | 665 +++---- railties/doc/guides/html/finders.html | 1134 ----------- railties/doc/guides/html/form_helpers.html | 972 ++++++---- .../guides/html/getting_started_with_rails.html | 1309 +++++-------- railties/doc/guides/html/i18n.html | 1296 ++++++------- railties/doc/guides/html/index.html | 310 +-- .../doc/guides/html/layouts_and_rendering.html | 944 ++++----- railties/doc/guides/html/migrations.html | 657 +++---- railties/doc/guides/html/performance_testing.html | 728 +++++++ railties/doc/guides/html/rails_on_rack.html | 450 +++++ railties/doc/guides/html/routing_outside_in.html | 1998 +++++++------------- railties/doc/guides/html/security.html | 1039 +++++----- .../guides/html/testing_rails_applications.html | 1892 +++++++++--------- 25 files changed, 9602 insertions(+), 12425 deletions(-) create mode 100644 railties/doc/guides/html/action_mailer_basics.html create mode 100644 railties/doc/guides/html/active_record_querying.html delete mode 100644 railties/doc/guides/html/benchmarking_and_profiling.html delete mode 100644 railties/doc/guides/html/finders.html create mode 100644 railties/doc/guides/html/performance_testing.html create mode 100644 railties/doc/guides/html/rails_on_rack.html (limited to 'railties/doc/guides/html') diff --git a/railties/doc/guides/html/2_2_release_notes.html b/railties/doc/guides/html/2_2_release_notes.html index 778144b688..0dec014c3e 100644 --- a/railties/doc/guides/html/2_2_release_notes.html +++ b/railties/doc/guides/html/2_2_release_notes.html @@ -1,307 +1,139 @@ - - Ruby on Rails 2.2 Release Notes - - - - - + + Ruby on Rails 2.2 Release Notes + + + + - - -

- - - -

Ruby on Rails 2.2 Release Notes

+ + +

+ + + +

Ruby on Rails 2.2 Release Notes

Rails 2.2 delivers a number of new and improved features. This list covers the major upgrades, but doesn't include every little bug fix and change. If you want to see everything, check out the list of commits in the main Rails repository on GitHub.

Along with Rails, 2.2 marks the launch of the Ruby on Rails Guides, the first results of the ongoing Rails Guides hackfest. This site will deliver high-quality documentation of the major features of Rails.

Rails 2.2 delivers a number of new and improved features. This list covers the major upgrades, but doesn’t include every little bug fix and change. If you want to see everything, check out the list of commits in the main Rails repository on GitHub.

1. Infrastructure

Rails 2.2 is a significant release for the infrastructure that keeps Rails humming along and connected to the rest of the world.

1.1. Internationalization

Rails 2.2 supplies an easy system for internationalization (or i18n, for those of you tired of typing).

Lead Contributors: Rails i18 Team @@ -311,7 +143,7 @@ Lead Contributors: Rails i18 Team

More information :

Official Rails i18 website @@ -331,12 +163,12 @@ More information :

1.2. Compatibility with Ruby 1.9 and JRuby

Along with thread safety, a lot of work has been done to make Rails work well with JRuby and the upcoming Ruby 1.9. With Ruby 1.9 being a moving target, running edge Rails on edge Ruby is still a hit-or-miss proposition, but Rails is ready to make the transition to Ruby 1.9 when the latter is released.

2. Documentation

The internal documentation of Rails, in the form of code comments, has been improved in numerous places. In addition, the Ruby on Rails Guides project is the definitive source for information on major Rails components. In its first official release, the Guides page includes:

Getting Started with Rails @@ -408,17 +240,16 @@ More information :

All told, the Guides provide tens of thousands of words of guidance for beginning and intermediate Rails developers.

If you want to generate these guides locally, inside your application:

All told, the Guides provide tens of thousands of words of guidance for beginning and intermediate Rails developers.

If you want to generate these guides locally, inside your application:

rake doc:guides
-

This will put the guides inside RAILS_ROOT/doc/guides and you may start surfing straight away by opening RAILS_ROOT/doc/guides/index.html in your favourite browser.

rake doc:guides

This will put the guides inside RAILS_ROOT/doc/guides and you may start surfing straight away by opening RAILS_ROOT/doc/guides/index.html in your favourite browser.

Lead Contributors: Rails Documentation Team @@ -433,7 +264,7 @@ Major contributions from Xav
More information:
-

4. Thread Safety

The work done to make Rails thread-safe is rolling out in Rails 2.2. Depending on your web server infrastructure, this means you can handle more requests with fewer copies of Rails in memory, leading to better server performance and higher utilization of multiple cores.

To enable multithreaded dispatching in production mode of your application, add the following line in your config/environments/production.rb:

config.threadsafe!
-

config.threadsafe!

More information :

Thread safety for your Rails @@ -525,10 +354,10 @@ More information :

5. Active Record

There are two big additions to talk about here: transactional migrations and pooled database transactions. There's also a new (and cleaner) syntax for join table conditions, as well as a number of smaller improvements.

There are two big additions to talk about here: transactional migrations and pooled database transactions. There’s also a new (and cleaner) syntax for join table conditions, as well as a number of smaller improvements.

5.1. Transactional Migrations

Historically, multiple-step Rails migrations have been a source of trouble. If something went wrong during a migration, everything before the error changed the database and everything after the error wasn't applied. Also, the migration version was stored as having been executed, which means that it couldn't be simply rerun by rake db:migrate:redo after you fix the problem. Transactional migrations change this by wrapping migration steps in a DDL transaction, so that if any of them fail, the entire migration is undone. In Rails 2.2, transactional migrations are supported on PostgreSQL out of the box. The code is extensible to other database types in the future - and IBM has already extended it to support the DB2 adapter.

Historically, multiple-step Rails migrations have been a source of trouble. If something went wrong during a migration, everything before the error changed the database and everything after the error wasn’t applied. Also, the migration version was stored as having been executed, which means that it couldn’t be simply rerun by rake db:migrate:redo after you fix the problem. Transactional migrations change this by wrapping migration steps in a DDL transaction, so that if any of them fail, the entire migration is undone. In Rails 2.2, transactional migrations are supported on PostgreSQL out of the box. The code is extensible to other database types in the future - and IBM has already extended it to support the DB2 adapter.

Lead Contributor: Adam Wiggins @@ -538,7 +367,7 @@ Lead Contributor: Adam Wiggins

More information:

DDL Transactions @@ -553,7 +382,7 @@ More information:

5.2. Connection Pooling

Connection pooling lets Rails distribute database requests across a pool of database connections that will grow to a maximum size (by default 5, but you can add a pool key to your database.yml to adjust this). This helps remove bottlenecks in applications that support many concurrent users. There's also a wait_timeout that defaults to 5 seconds before giving up. ActiveRecord::Base.connection_pool gives you direct access to the pool if you need it.

Connection pooling lets Rails distribute database requests across a pool of database connections that will grow to a maximum size (by default 5, but you can add a pool key to your database.yml to adjust this). This helps remove bottlenecks in applications that support many concurrent users. There’s also a wait_timeout that defaults to 5 seconds before giving up. ActiveRecord::Base.connection_pool gives you direct access to the pool if you need it.

username: root database: sample_development pool: 10 - wait_timeout: 10 -

Lead Contributor: Nick Sieger @@ -576,17 +404,17 @@ Lead Contributor: Nick Sieger
More information:
-
5.3. Hashes for Join Table Conditions
-
You can now specify conditions on join tables using a hash. This is a big help if you need to query across complex joins.
+
You can now specify conditions on join tables using a hash. This is a big help if you need to query across complex joins.

end # Get all products with copyright-free photos: -Product.all(:joins => :photos, :conditions => { :photos => { :copyright => false }}) -
-

More information:
-
5.4. New Dynamic Finders
-
Two new sets of methods have been added to Active Record's dynamic finders family.
+
Two new sets of methods have been added to Active Record’s dynamic finders family.

5.4.1. find_last_by_<attribute>
-
The find_last_by_<attribute> method is equivalent to Model.last(:conditions ⇒ {:attribute ⇒ value})
+
The find_last_by_<attribute> method is equivalent to Model.last(:conditions => {:attribute => value})
```
# Get the last user who signed up from London
-User.find_last_by_city('London')
-
```
-

Lead Contributor: Emilio Tagua @@ -637,16 +463,15 @@ Lead Contributor: 5.4.2. find_by_<attribute>! -
The new bang! version of find_by_<attribute>! is equivalent to Model.first(:conditions ⇒ {:attribute ⇒ value}) || raise ActiveRecord::RecordNotFound Instead of returning nil if it can't find a matching record, this method will raise an exception if it cannot find a match.
+
The new bang! version of find_by_<attribute>! is equivalent to Model.first(:conditions => {:attribute => value}) || raise ActiveRecord::RecordNotFound Instead of returning nil if it can’t find a matching record, this method will raise an exception if it cannot find a match.
```
# Raise ActiveRecord::RecordNotFound exception if 'Moby' hasn't signed up yet!
-User.find_by_name!('Moby')
-
```
-

Lead Contributor: Josh Susser @@ -654,8 +479,8 @@ Lead Contributor: Josh Susser

5.5. Associations Respect Private/Protected Scope

Active Record association proxies now respect the scope of methods on the proxied object. Previously (given User has_one :account) @user.account.private_method would call the private method on the associated Account object. That fails in Rails 2.2; if you need this functionality, you should use @user.account.send(:private_method) (or make the method public instead of private or protected). Please note that if you're overriding method_missing, you should also override respond_to to match the behavior in order for associations to function normally.

Active Record association proxies now respect the scope of methods on the proxied object. Previously (given User has_one :account) @user.account.private_method would call the private method on the associated Account object. That fails in Rails 2.2; if you need this functionality, you should use @user.account.send(:private_method) (or make the method public instead of private or protected). Please note that if you’re overriding method_missing, you should also override respond_to to match the behavior in order for associations to function normally.

Lead Contributor: Adam Milligan @@ -665,7 +490,7 @@ Lead Contributor: Adam Milligan

More information:

Rails 2.2 Change: Private Methods on Association Proxies are Private @@ -675,7 +500,7 @@ More information:

5.6. Other ActiveRecord Changes

rake db:migrate:redo now accepts an optional VERSION to target that specific migration to redo @@ -688,7 +513,7 @@ Set config.active_record.timestamped_migrations = false to have migrati
-Counter cache columns (for associations declared with :counter_cache ⇒ true) do not need to be initialized to zero any longer. +Counter cache columns (for associations declared with :counter_cache => true) do not need to be initialized to zero any longer.
@@ -700,9 +525,9 @@ Counter cache columns (for associations declared with :counter_cache ⇒

6. Action Controller

-On the controller side, there are several changes that will help tidy up your routes. There are also some internal changes in the routing engine to lower memory usage on complex applications. +On the controller side, there are several changes that will help tidy up your routes. There are also some internal changes in the routing engine to lower memory usage on complex applications. 6.1. Shallow Route Nesting -Shallow route nesting provides a solution to the well-known difficulty of using deeply-nested resources. With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with. +Shallow route nesting provides a solution to the well-known difficulty of using deeply-nested resources. With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with.

publisher.resources :magazines do |magazine| magazine.resources :photos end -end -

This will enable recognition of (among others) these routes:

+end

This will enable recognition of (among others) these routes:

/publishers/1           ==> publisher_path(1)
@@ -723,7 +547,7 @@ http://www.gnu.org/software/src-highlite -->
 /magazines/2/photos     ==> magazines_photos_path(2)
 /photos/3               ==> photo_path(3)

Lead Contributor: S. Brent Faulkner @@ -733,7 +557,7 @@ Lead Contributor: S. Brent Faulkner
More information:
-
6.2. Method Arrays for Member or Collection Routes
-
You can now supply an array of methods for new member or collection routes. This removes the annoyance of having to define a route as accepting any verb as soon as you need it to handle more than one. With Rails 2.2, this is a legitimate route declaration:
+
You can now supply an array of methods for new member or collection routes. This removes the annoyance of having to define a route as accepting any verb as soon as you need it to handle more than one. With Rails 2.2, this is a legitimate route declaration:
-
```
map.resources :photos, :collection => { :search => [:get, :post] }
-
```
-

Lead Contributor: Brennan Dunn @@ -764,16 +587,15 @@ Lead Contributor: Brennan Dunn

6.3. Resources With Specific Actions

By default, when you use map.resources to create a route, Rails generates routes for seven default actions (index, show, create, new, edit, update, and destroy). But each of these routes takes up memory in your application, and causes Rails to generate additional routing logic. Now you can use the :only and :except options to fine-tune the routes that Rails will generate for resources. You can supply a single action, an array of actions, or the special :all or :none options. These options are inherited by nested resources.

map.resources :photos, :only => [:index, :show]
-map.resources :products, :except => :destroy
-

Lead Contributor: Tom Stuart @@ -781,7 +603,7 @@ Lead Contributor: Tom Stuart

6.4. Other Action Controller Changes

You can now easily show a custom error page for exceptions raised while routing a request. @@ -826,7 +648,7 @@ Polymorphic URLs behave more sensibly if a passed parameter is nil. For example,

7. Action View

javascript_include_tag and stylesheet_link_tag support a new :recursive option to be used along with :all, so that you can load an entire tree of files with a single line of code. @@ -839,7 +661,7 @@ The included Prototype javascript library has been upgraded to version 1.6.0.3.
-RJS#page.reload to reload the browser's current location via javascript +RJS#page.reload to reload the browser’s current location via javascript
@@ -851,28 +673,28 @@ The atom_feed helper now takes an :instruct option to let you

8. Action Mailer

Action Mailer now supports mailer layouts. You can make your HTML emails as pretty as your in-browser views by supplying an appropriately-named layout - for example, the CustomerMailer class expects to use layouts/customer_mailer.html.erb.

More information:
-
-
Action Mailer now offers built-in support for GMail's SMTP servers, by turning on STARTTLS automatically. This requires Ruby 1.8.7 to be installed.
+
Action Mailer now offers built-in support for GMail’s SMTP servers, by turning on STARTTLS automatically. This requires Ruby 1.8.7 to be installed.

9. Active Support

Active Support now offers built-in memoization for Rails applications, the each_with_object method, prefix support on delegates, and various other new utility methods.

9.1. Memoization

Memoization is a pattern of initializing a method once and then stashing its value away for repeat use. You've probably used this pattern in your own applications:

Memoization is a pattern of initializing a method once and then stashing its value away for repeat use. You’ve probably used this pattern in your own applications:

def full_name
   @full_name ||= "#{first_name} #{last_name}"
-end
-

Memoization lets you handle this task in a declarative fashion:

+end

Memoization lets you handle this task in a declarative fashion:

def full_name "#{first_name} #{last_name}" end -memoize :full_name -

Other features of memoization include unmemoize, unmemoize_all, and memoize_all to turn memoization on or off.

Lead Contributor: Josh Peek @@ -906,10 +726,10 @@ Lead Contributor: Josh Peek
More information:
-

Lead Contributor: Adam Keys

9.3. Delegates With Prefixes

If you delegate behavior from one class to another, you can now specify a prefix that will be used to identify the delegated methods. For example:

class Vendor < ActiveRecord::Base
   has_one :account
   delegate :email, :password, :to => :account, :prefix => true
-end
-

This will produce delegated methods vendor#account_email and vendor#account_password. You can also specify a custom prefix:

end

This will produce delegated methods vendor#account_email and vendor#account_password. You can also specify a custom prefix:

class Vendor < ActiveRecord::Base
   has_one :account
   delegate :email, :password, :to => :account, :prefix => :owner
-end
-

This will produce delegated methods vendor#owner_email and vendor#owner_password.

Lead Contributor: Daniel Schierbeck

end

This will produce delegated methods vendor#owner_email and vendor#owner_password.

Lead Contributor: Daniel Schierbeck

9.4. Other Active Support Changes

Extensive updates to ActiveSupport::Multibyte, including Ruby 1.9 compatibility fixes. @@ -999,17 +816,17 @@ The included TzInfo library has been upgraded to version 0.3.12.
-ActiveSuport::StringInquirer gives you a pretty way to test for equality in strings: ActiveSupport::StringInquirer.new("abc").abc? ⇒ true +ActiveSuport::StringInquirer gives you a pretty way to test for equality in strings: ActiveSupport::StringInquirer.new("abc").abc? => true

10. Railties

In Railties (the core code of Rails itself) the biggest changes are in the config.gems mechanism.

10.1. `config.gems`

To avoid deployment issues and make Rails applications more self-contained, it's possible to place copies of all of the gems that your Rails application requires in /vendor/gems. This capability first appeared in Rails 2.1, but it's much more flexible and robust in Rails 2.2, handling complicated dependencies between gems. Gem management in Rails includes these commands:

To avoid deployment issues and make Rails applications more self-contained, it’s possible to place copies of all of the gems that your Rails application requires in /vendor/gems. This capability first appeared in Rails 2.1, but it’s much more flexible and robust in Rails 2.2, handling complicated dependencies between gems. Gem management in Rails includes these commands:

config.gem gem_name in your config/environment.rb file @@ -1046,8 +863,8 @@ The included TzInfo library has been upgraded to version 0.3.12.

You can unpack or install a single gem by specifying GEM=gem_name on the command line.

Lead Contributor: Matt Jones @@ -1057,10 +874,10 @@ Lead Contributor: Matt Jones
More information:
-
-

diff --git a/railties/doc/guides/html/action_mailer_basics.html b/railties/doc/guides/html/action_mailer_basics.html new file mode 100644 index 0000000000..56451818eb --- /dev/null +++ b/railties/doc/guides/html/action_mailer_basics.html @@ -0,0 +1,197 @@ + + + + + Action Mailer Basics + + + + + + + + +

+ + + +

Action Mailer Basics

This guide should provide you with all you need to get started in sending emails from your application, and will also cover how to test your mailers.

1. What is Action Mailer?

Action Mailer allows you to send email from your application using a mailer model and views. +Yes, that is correct, in Rails, emails are used by creating Models that inherit from ActionMailer::Base. They live alongside other models in /app/models BUT they have views just like controllers that appear alongside other views in app/views.

2. Quick walkthrough to creating a Mailer

Let’s say you want to send a welcome email to a user after they signup. Here is how you would go about this:

2.1. 1. Create the mailer:

./script/generate mailer UserMailer
+exists  app/models/
+create  app/views/user_mailer
+exists  test/unit/
+create  test/fixtures/user_mailer
+create  app/models/user_mailer.rb
+create  test/unit/user_mailer_test.rb

So we got the model, the fixtures, and the tests all created for us

2.2. 2. Edit the model:

class UserMailer < ActionMailer::Base
+
+end

Lets add a method called welcome_email, that will send an email to the user’s registered email address:

class UserMailer < ActionMailer::Base
+
+  def welcome_email(user)
+    recipients    user.email
+    from          "My Awesome Site Notifications<notifications@example.com>"
+    subject       "Welcome to My Awesome Site"
+    sent_on       Time.now
+    body          {:user => user, :url => "http://example.com/login"}
+    content_type  "text/html"
+  end
+
+end

So what do we have here? +recipients: who the recipients are, put in an array for multiple, ie, @recipients = ["user1@example.com", "user2@example.com"] +from: Who the email will appear to come from in the recipients' mailbox +subject: The subject of the email +sent_on: Timestamp for the email +content_type: The content type, by default is text/plain

How about @body[:user]? Well anything you put in the @body hash will appear in the mailer view (more about mailer views below) as an instance variable ready for you to use, ie, in our example the mailer view will have a @user instance variable available for its consumption.

2.3. 3. Create the mailer view

The file can look like:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+  <head>
+    <meta content='text/html; charset=iso-8859-1' http-equiv='Content-Type' />
+  </head>
+  <body>
+    <h1>Welcome to example.com, <%= @user.first_name %></h1>
+
+    <p>
+      You have successfully signed up to example.com, and your username is: <%= @user.login %>.<br/>
+      To login to the site, just follow this link: <%= @url %>.
+    </p>
+    <p>Thanks for joining and have a great day!</p>
+  </body>
+</html>

2.4. 4. Wire it up so that the system sends the email when a user signs up

There are 3 was to achieve this. One is to send the email from the controller that sends the email, another is to put it in a before_create block in the user model, and the last one is to use an observer on the user model. Whether you use the second or third methods is up to you, but staying away from the first is recommended. Not because it’s wrong, but because it keeps your controller clean, and keeps all logic related to the user model within the user model. This way, whichever way a user is created (from a web form, or from an API call, for example), we are guaranteed that the email will be sent.

# Code that already exists
+
+Rails::Initializer.run do |config|
+
+  # Code that already exists
+
+  config.active_record.observers = :user_observer
+
+end

# Code that already exists
+
+Rails::Initializer.run do |config|
+
+  # Code that already exists
+
+  config.load_paths += %W(#{RAILS_ROOT}/app/observers)
+
+  config.active_record.observers = :user_observer
+
+end

ALMOST THERE :) Now all we need is that danged observer, and we’re done:

class UserObserver < ActiveRecord::Observer
+  def after_create(user)
+    UserMailer.deliver_welcome_email(user)
+  end
+end

Notice how we call deliver_welcome_email? Where is that method? Well if you remember, we created a method called welcome_email in UserMailer, right? Well, as part of the "magic" of rails, we deliver the email identified by welcome_email by calling deliver_welcome_email.

That’s it! Now whenever your users signup, they will be greeted with a nice welcome email. Next up, we’ll talk about how to test a mailer model.

3. Mailer Testing

+ +

+ + diff --git a/railties/doc/guides/html/actioncontroller_basics.html b/railties/doc/guides/html/actioncontroller_basics.html index 4af157d4f7..f5b25a4d7a 100644 --- a/railties/doc/guides/html/actioncontroller_basics.html +++ b/railties/doc/guides/html/actioncontroller_basics.html @@ -1,300 +1,130 @@ - - Action Controller basics - - - - - + + Action Controller basics + + + + - -

- - - -

Action Controller basics

+ + + +

Action Controller basics

In this guide you will learn how controllers work and how they fit into the request cycle in your application. After reading this guide, you will be able to:

Follow the flow of a request through a controller @@ -312,17 +142,17 @@ Work with filters to execute code during request processing
-Use Action Controller's built-in HTTP authentication +Use Action Controller’s built-in HTTP authentication
-Stream data directly to the user's browser +Stream data directly to the user’s browser
-Filter sensitive parameters so they do not appear in the application's log +Filter sensitive parameters so they do not appear in the application’s log
@@ -335,9 +165,9 @@ Deal with exceptions that may be raised during request processing

1. What Does a Controller do?

Action Controller is the C in MVC. After routing has determined which controller to use for a request, your controller is responsible for making sense of the request and producing the appropriate output. Luckily, Action Controller does most of the groundwork for you and uses smart conventions to make this as straight-forward as possible.

For most conventional RESTful applications, the controller will receive the request (this is invisible to you as the developer), fetch or save data from a model and use a view to create HTML output. If your controller needs to do things a little differently, that's not a problem, this is just the most common way for a controller to work.

A controller can thus be thought of as a middle man between models and views. It makes the model data available to the view so it can display that data to the user, and it saves or updates data from the user to the model.

For most conventional RESTful applications, the controller will receive the request (this is invisible to you as the developer), fetch or save data from a model and use a view to create HTML output. If your controller needs to do things a little differently, that’s not a problem, this is just the most common way for a controller to work.

- +

@@ -349,7 +179,7 @@ Deal with exceptions that may be raised during request processing

2. Methods and Actions

A controller is a Ruby class which inherits from ApplicationController and has methods just like any other class. When your application receives a request, the routing will determine which controller and action to run, then Rails creates an instance of that controller and runs the public method with the same name as the action.

def new
   @client = Client.new
-end
-

The Layouts & rendering guide explains this in more detail.

ApplicationController inherits from ActionController::Base, which defines a number of helpful methods. This guide will cover some of these, but if you're curious to see what's in there, you can see all of them in the API documentation or in the source itself.

+end

The Layouts & rendering guide explains this in more detail.

ApplicationController inherits from ActionController::Base, which defines a number of helpful methods. This guide will cover some of these, but if you’re curious to see what’s in there, you can see all of them in the API documentation or in the source itself.

3. Parameters

You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, called query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from a HTML form which has been filled in by the user. It's called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the params hash in your controller:

You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, called query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from a HTML form which has been filled in by the user. It’s called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the params hash in your controller:

end end -end -

+end

3.1. Hash and Array Parameters

The params hash is not limited to one-dimensional keys and values. It can contain arrays and (nested) hashes. To send an array of values, append "[]" to the key name:

GET /clients?ids[]=1&ids[]=2&ids[]=3

@@ -436,11 +263,11 @@ http://www.gnu.org/software/src-highlite -->

The actual URL in this example will be encoded as "/clients?ids%5b%5d=1&ids%5b%5d=2&ids%5b%5b=3" as [ and ] are not allowed in URLs. Most of the time you don't have to worry about this because the browser will take care of it for you, and Rails will decode it back when it receives it, but if you ever find yourself having to send those requests to the server manually you have to keep this in mind.

The actual URL in this example will be encoded as "/clients?ids%5b%5d=1&ids%5b%5d=2&ids%5b%5b=3" as [ and ] are not allowed in URLs. Most of the time you don’t have to worry about this because the browser will take care of it for you, and Rails will decode it back when it receives it, but if you ever find yourself having to send those requests to the server manually you have to keep this in mind.

The value of params[:ids] will now be ["1", "2", "3"]. Note that parameter values are always strings; Rails makes no attempt to guess or cast the type.

To send a hash you include the key name inside the brackets:

The value of params[:ids] will now be ["1", "2", "3"]. Note that parameter values are always strings; Rails makes no attempt to guess or cast the type.

To send a hash you include the key name inside the brackets:

<form action="/clients" method="post">
@@ -450,10 +277,10 @@ http://www.gnu.org/software/src-highlite -->
   <input type="text" name="client[address][city]" value="Carrot City" />
 </form>

The value of params[:client] when this form is submitted will be {"name" ⇒ "Acme", "phone" ⇒ "12345", "address" ⇒ {"postcode" ⇒ "12345", "city" ⇒ "Carrot City"}}. Note the nested hash in params[:client][:address].

Note that the params hash is actually an instance of HashWithIndifferentAccess from Active Support which is a subclass of Hash which lets you use symbols and strings interchangeably as keys.

The value of params[:client] when this form is submitted will be {"name" => "Acme", "phone" => "12345", "address" => {"postcode" => "12345", "city" => "Carrot City"}}. Note the nested hash in params[:client][:address].

Note that the params hash is actually an instance of HashWithIndifferentAccess from Active Support which is a subclass of Hash which lets you use symbols and strings interchangeably as keys.

3.2. Routing Parameters

The params hash will always contain the :controller and :action keys, but you should use the methods controller_name and action_name instead to access these values. Any other parameters defined by the routing, such as :id will also be available. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the :status parameter in a "pretty" URL:

# ...
 map.connect "/clients/:status", :controller => "clients", :action => "index", :foo => "bar"
-# ...
-

In this case, when a user opens the URL /clients/active, params[:status] will be set to "active". When this route is used, params[:foo] will also be set to "bar" just like it was passed in the query string in the same way params[:action] will contain "index".

+# ...

3.3. `default_url_options`

You can set global default parameters that will be used when generating URLs with default_url_options. To do this, define a method with that name in your controller:

class ApplicationController < ActionController::Base
@@ -477,12 +303,12 @@ map.connect "/c
 
 end

These options will be used as a starting-point when generating, so it's possible they'll be overridden by url_for. Because this method is defined in the controller, you can define it on ApplicationController so it would be used for all URL generation, or you could define it on only one controller for all URLs generated there.

These options will be used as a starting-point when generating, so it’s possible they’ll be overridden by url_for. Because this method is defined in the controller, you can define it on ApplicationController so it would be used for all URL generation, or you could define it on only one controller for all URLs generated there.

4. Session

Your application has a session for each user in which you can store small amounts of data that will be persisted between requests. The session is only available in the controller and the view and can use one of a number of different storage mechanisms:

CookieStore - Stores everything on the client. @@ -504,62 +330,28 @@ ActiveRecordStore - Stores the data in a database using Active Record.

All session stores use a cookie - this is required and Rails does not allow any part of the session to be passed in any other way (e.g. you can't use the query string to pass a session ID) because of security concerns (it's easier to hijack a session when the ID is part of the URL).

Most stores use a cookie to store the session ID which is then used to look up the session data on the server. The default and recommended store, the CookieStore, does not store session data on the server, but in the cookie itself. The data is cryptographically signed to make it tamper-proof, but it is not encrypted, so anyone with access to it can read its contents but not edit it (Rails will not accept it if it has been edited). It can only store about 4kB of data - much less than the others - but this is usually enough. Storing large amounts of data is discouraged no matter which session store your application uses. You should especially avoid storing complex objects (anything other than basic Ruby objects, the most common example being model instances) in the session, as the server might not be able to reassemble them between requests, which will result in an error. The CookieStore has the added advantage that it does not require any setting up beforehand - Rails will generate a "secret key" which will be used to sign the cookie when you create the application.

Read more about session storage in the Security Guide.

If you need a different session storage mechanism, you can change it in the config/environment.rb file:

All session stores use a cookie - this is required and Rails does not allow any part of the session to be passed in any other way (e.g. you can’t use the query string to pass a session ID) because of security concerns (it’s easier to hijack a session when the ID is part of the URL).

Read more about session storage in the Security Guide.

If you need a different session storage mechanism, you can change it in the config/environment.rb file:

# Set to one of [:active_record_store, :drb_store, :mem_cache_store, :cookie_store]
-config.action_controller.session_store = :active_record_store
-

4.1. Disabling the Session

Sometimes you don't need a session. In this case, you can turn it off to avoid the unnecessary overhead. To do this, use the session class method in your controller:

class ApplicationController < ActionController::Base
-  session :off
-end
-

You can also turn the session on or off for a single controller:

# The session is turned off by default in ApplicationController, but we
-# want to turn it on for log in/out.
-class LoginsController < ActionController::Base
-  session :on
-end
-

Or even for specified actions:

class ProductsController < ActionController::Base
-  session :on, :only => [:create, :update]
-end
-

4.2. Accessing the Session

In your controller you can access the session through the session instance method.

4.1. Accessing the Session

In your controller you can access the session through the session instance method.

- +

There are two session methods, the class and the instance method. The class method which is described above is used to turn the session on and off while the instance method described below is used to access session values. Sessions are lazily loaded. If you don’t access sessions in your action’s code, they will not be loaded. Hence you will never need to disable sessions, just not accessing them will do the job.

Session values are stored using key/value pairs like a hash:

end end -end -

To remove something from the session, assign that key to be nil:

+end

To remove something from the session, assign that key to be nil:

redirect_to root_url end -end -

To reset the entire session, use reset_session.

4.3. The flash

The flash is a special part of the session which is cleared with each request. This means that values stored there will only be available in the next request, which is useful for storing error messages etc. It is accessed in much the same way as the session, like a hash. Let's use the act of logging out as an example. The controller can send a message which will be displayed to the user on the next request:

+end

To reset the entire session, use reset_session.

4.2. The flash

The flash is a special part of the session which is cleared with each request. This means that values stored there will only be available in the next request, which is useful for storing error messages etc. It is accessed in much the same way as the session, like a hash. Let’s use the act of logging out as an example. The controller can send a message which will be displayed to the user on the next request:

redirect_to root_url end -end -

The destroy action redirects to the application's root_url, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to display eventual errors or notices from the flash in the application's layout:

+end

The destroy action redirects to the application’s root_url, where the message will be displayed. Note that it’s entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It’s conventional to display eventual errors or notices from the flash in the application’s layout:

<html>
@@ -648,8 +436,8 @@ http://www.gnu.org/software/src-highlite -->
   </body>
 </html>

This way, if an action sets an error or a notice message, the layout will display it automatically.

If you want a flash value to be carried over to another request, use the keep method:

This way, if an action sets an error or a notice message, the layout will display it automatically.

If you want a flash value to be carried over to another request, use the keep method:

redirect_to users_url end -end -

4.3.1. `flash.now`

By default, adding values to the flash will make them available to the next request, but sometimes you may want to access those values in the same request. For example, if the create action fails to save a resource and you render the new template directly, that's not going to result in a new request, but you may still want to display a message using the flash. To do this, you can use flash.now in the same way you use the normal flash:

+end

4.2.1. `flash.now`

By default, adding values to the flash will make them available to the next request, but sometimes you may want to access those values in the same request. For example, if the create action fails to save a resource and you render the new template directly, that’s not going to result in a new request, but you may still want to display a message using the flash. To do this, you can use flash.now in the same way you use the normal flash:

end end -end -

end

5. Cookies

Your application can store small amounts of data on the client - called cookies - that will be persisted across requests and even sessions. Rails provides easy access to cookies via the cookies method, which - much like the session - works like a hash:

end end -end -

Note that while for session values you set the key to nil, to delete a cookie value you should use cookies.delete(:key).

+end

Note that while for session values you set the key to nil, to delete a cookie value you should use cookies.delete(:key).

6. Filters

Filters are methods that are run before, after or "around" a controller action. For example, one filter might check to see if the logged in user has the right credentials to access that particular controller or action. Filters are inherited, so if you set a filter on ApplicationController, it will be run on every controller in your application. A common, simple filter is one which requires that a user is logged in for an action to be run. You can define the filter method this way:

before_filter :require_login -end -

In this example, the filter is added to ApplicationController and thus all controllers in the application. This will make everything in the application require the user to be logged in in order to use it. For obvious reasons (the user wouldn't be able to log in in the first place!), not all controllers or actions should require this. You can prevent this filter from running before particular actions with skip_before_filter:

+end

In this example, the filter is added to ApplicationController and thus all controllers in the application. This will make everything in the application require the user to be logged in in order to use it. For obvious reasons (the user wouldn’t be able to log in in the first place!), not all controllers or actions should require this. You can prevent this filter from running before particular actions with skip_before_filter:

skip_before_filter :require_login, :only => [:new, :create] -end -

Now, the LoginsController's new and create actions will work as before without requiring the user to be logged in. The :only option is used to only skip this filter for these actions, and there is also an :except option which works the other way. These options can be used when adding filters too, so you can add a filter which only runs for selected actions in the first place.

+end

Now, the LoginsController’s new and create actions will work as before without requiring the user to be logged in. The :only option is used to only skip this filter for these actions, and there is also an :except option which works the other way. These options can be used when adding filters too, so you can add a filter which only runs for selected actions in the first place.

6.1. After Filters and Around Filters

In addition to the before filters, you can run filters after an action has run or both before and after. The after filter is similar to the before filter, but because the action has already been run it has access to the response data that's about to be sent to the client. Obviously, after filters can not stop the action from running. Around filters are responsible for running the action, but they can choose not to, which is the around filter's way of stopping it.

In addition to the before filters, you can run filters after an action has run or both before and after. The after filter is similar to the before filter, but because the action has already been run it has access to the response data that’s about to be sent to the client. Obviously, after filters can not stop the action from running. Around filters are responsible for running the action, but they can choose not to, which is the around filter’s way of stopping it.

before_filter { |controller| redirect_to new_login_url unless controller.send(:logged_in?) } -end -

Note that the filter in this case uses send because the logged_in? method is private and the filter is not run in the scope of the controller. This is not the recommended way to implement this particular filter, but in more simple cases it might be useful.

The second way is to use a class (actually, any object that responds to the right methods will do) to handle the filtering. This is useful in cases that are more complex than can not be implemented in a readable and reusable way using the two other methods. As an example, you could rewrite the login filter again to use a class:

end

end end -end -

Again, this is not an ideal example for this filter, because it's not run in the scope of the controller but gets the controller passed as an argument. The filter class has a class method filter which gets run before or after the action, depending on if it's a before or after filter. Classes used as around filters can also use the same filter method, which will get run in the same way. The method must yield to execute the action. Alternatively, it can have both a before and an after method that are run before and after the action.

The Rails API documentation has more information on using filters.

+end

Again, this is not an ideal example for this filter, because it’s not run in the scope of the controller but gets the controller passed as an argument. The filter class has a class method filter which gets run before or after the action, depending on if it’s a before or after filter. Classes used as around filters can also use the same filter method, which will get run in the same way. The method must yield to execute the action. Alternatively, it can have both a before and an after method that are run before and after the action.

The Rails API documentation has more information on using filters.

7. Verification

Verifications make sure certain criteria are met in order for a controller or action to run. They can specify that a certain key (or several keys in the form of an array) is present in the params, session or flash hashes or that a certain HTTP method was used or that the request was made using XMLHTTPRequest (Ajax). The default action taken when these criteria are not met is to render a 400 Bad Request response, but you can customize this by specifying a redirect URL or rendering something else and you can also add flash messages and HTTP headers to the response. It is described in the API documentation as "essentially a special kind of before_filter".

Here's an example of using verification to make sure the user supplies a username and a password in order to log in:

Here’s an example of using verification to make sure the user supplies a username and a password in order to log in:

end end -end -

Now the create action won't run unless the "username" and "password" parameters are present, and if they're not, an error message will be added to the flash and the new action will be rendered. But there's something rather important missing from the verification above: It will be used for every action in LoginsController, which is not what we want. You can limit which actions it will be used for with the :only and :except options just like a filter:

+end

Now the create action won’t run unless the "username" and "password" parameters are present, and if they’re not, an error message will be added to the flash and the new action will be rendered. But there’s something rather important missing from the verification above: It will be used for every action in LoginsController, which is not what we want. You can limit which actions it will be used for with the :only and :except options just like a filter:

:add_flash => {:error => "Username and password required to log in"}, :only => :create # Only run this verification for the "create" action -end -

+end

8. Request Forgery Protection

Cross-site request forgery is a type of attack in which a site tricks a user into making requests on another site, possibly adding, modifying or deleting data on that site without the user's knowledge or permission. The first step to avoid this is to make sure all "destructive" actions (create, update and destroy) can only be accessed with non-GET requests. If you're following RESTful conventions you're already doing this. However, a malicious site can still send a non-GET request to your site quite easily, and that's where the request forgery protection comes in. As the name says, it protects from forged requests. The way this is done is to add a non-guessable token which is only known to your server to each request. This way, if a request comes in without the proper token, it will be denied access.

If you generate a form like this:

Cross-site request forgery is a type of attack in which a site tricks a user into making requests on another site, possibly adding, modifying or deleting data on that site without the user’s knowledge or permission. The first step to avoid this is to make sure all "destructive" actions (create, update and destroy) can only be accessed with non-GET requests. If you’re following RESTful conventions you’re already doing this. However, a malicious site can still send a non-GET request to your site quite easily, and that’s where the request forgery protection comes in. As the name says, it protects from forged requests. The way this is done is to add a non-guessable token which is only known to your server to each request. This way, if a request comes in without the proper token, it will be denied access.

If you generate a form like this:

<% form_for @user do |f| -%>
   <%= f.text_field :username %>
   <%= f.text_field :password -%>
-<% end -%>
-

You will see how the token gets added as a hidden field:

+<% end -%>

You will see how the token gets added as a hidden field:

<form action="/users/1" method="post">
 <div><!-- ... --><input type="hidden" value="67250ab105eb5ad10851c00a5621854a23af5489" name="authenticity_token"/></div>
 <!-- Fields -->
-</form>
-

Rails adds this token to every form that's generated using the form helpers, so most of the time you don't have to worry about it. If you're writing a form manually or need to add the token for another reason, it's available through the method form_authenticity_token:

+</form> +

Rails adds this token to every form that’s generated using the form helpers, so most of the time you don’t have to worry about it. If you’re writing a form manually or need to add the token for another reason, it’s available through the method form_authenticity_token:

Example: Add a JavaScript variable containing the token for use with Ajax

Add a JavaScript variable containing the token for use with Ajax

<%= javascript_tag "MyApp.authenticity_token = '#{form_authenticity_token}'" %>

The Security Guide has more about this and a lot of other security-related issues that you should be aware of when developing a web application.

9. The `request` and `response` Objects

In every controller there are two accessor methods pointing to the request and the response objects associated with the request cycle that is currently in execution. The request method contains an instance of AbstractRequest and the response method returns a response object representing what is going to be sent back to the client.

9.1. The `request` Object

The request object contains a lot of useful information about the request coming in from the client. To get a full list of the available methods, refer to the API documentation. Among the properties that you can access on this object are:

host - The hostname used for this request. @@ -934,7 +709,7 @@ host - The hostname used for this request.
-domain(n=2) - The hostname's first n segments, starting from the right (the TLD) +domain(n=2) - The hostname’s first n segments, starting from the right (the TLD)
@@ -984,10 +759,10 @@ url - The entire URL used for the request.

9.1.1. `path_parameters`, `query_parameters` and `request_parameters`

Rails collects all of the parameters sent along with the request in the params hash, whether they are sent as part of the query string or the post body. The request object has three accessors that give you access to these parameters depending on where they came from. The query_parameters hash contains parameters that were sent as part of the query string while the request_parameters hash contains parameters sent as part of the post body. The path_parameters hash contains parameters that were recognized by the routing as being part of the path leading to this particular controller and action.

9.2. The `response` Object

The response object is not usually used directly, but is built up during the execution of the action and rendering of the data that is being sent back to the user, but sometimes - like in an after filter - it can be useful to access the response directly. Some of these accessor methods also have setters, allowing you to change their values.

body - This is the string of data being sent back to the client. This is most often HTML. @@ -1020,18 +795,17 @@ headers - Headers used for the response.

9.2.1. Setting Custom Headers

If you want to set custom headers for a response then response.headers is the place to do it. The headers attribute is a hash which maps header names to their values, and Rails will set some of them - like "Content-Type" - automatically. If you want to add or change a header, just assign it to headers with the name and value:

response.headers["Content-Type"] = "application/pdf"
-

response.headers["Content-Type"] = "application/pdf"

10. HTTP Basic Authentication

Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider an administration section which will only be available by entering a username and a password into the browser's HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, authenticate_or_request_with_http_basic.

Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider an administration section which will only be available by entering a username and a password into the browser’s HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, authenticate_or_request_with_http_basic.

send_data("#{RAILS_ROOT}/files/clients/#{client.id}.pdf", :filename => "#{client.name}.pdf", :type => "application/pdf") end -end -

This will read and stream the file 4Kb at the time, avoiding loading the entire file into memory at once. You can turn off streaming with the :stream option or adjust the block size with the :buffer_size option.

+end

- +

Be careful when using (or just don't use) "outside" data (params, cookies, etc) to locate the file on disk, as this is a security risk that might allow someone to gain access to files they are not meant to see.

Be careful when using (or just don’t use) "outside" data (params, cookies, etc) to locate the file on disk, as this is a security risk that might allow someone to gain access to files they are not meant to see.

@@ -1122,7 +893,7 @@ http://www.gnu.org/software/src-highlite -->

11.2. RESTful Downloads

While send_data works just fine, if you are creating a RESTful application having separate actions for file downloads is usually not necessary. In REST terminology, the PDF file from the example above can be considered just another representation of the client resource. Rails provides an easy and quite sleek way of doing "RESTful downloads". Here's how you can rewrite the example so that the PDF download is a part of the show action, without any streaming:

While send_data works just fine, if you are creating a RESTful application having separate actions for file downloads is usually not necessary. In REST terminology, the PDF file from the example above can be considered just another representation of the client resource. Rails provides an easy and quite sleek way of doing "RESTful downloads". Here’s how you can rewrite the example so that the PDF download is a part of the show action, without any streaming:

end end -end -

In order for this example to work, you have to add the PDF MIME type to Rails. This can be done by adding the following line to the file config/initializers/mime_types.rb:

+end +

In order for this example to work, you have to add the PDF MIME type to Rails. This can be done by adding the following line to the file config/initializers/mime_types.rb:

Mime::Type.register "application/pdf", :pdf
-

Mime::Type.register "application/pdf", :pdf

@@ -1158,7 +927,7 @@ http://www.gnu.org/software/src-highlite -->

Configuration files are not reloaded on each request, so you have to restart the server in order for their changes to take effect.

Now the user can request to get a PDF version of a client just by adding ".pdf" to the URL:

GET /clients/1.pdf

@@ -1166,7 +935,7 @@ http://www.gnu.org/software/src-highlite -->

12. Parameter Filtering

Rails keeps a log file for each environment (development, test and production) in the log folder. These are extremely useful when debugging what's actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. The filter_parameter_logging method can be used to filter out sensitive information from the log. It works by replacing certain values in the params hash with "[FILTERED]" as they are written to the log. As an example, let's see how to filter all parameters with keys that include "password":

Rails keeps a log file for each environment (development, test and production) in the log folder. These are extremely useful when debugging what’s actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. The filter_parameter_logging method can be used to filter out sensitive information from the log. It works by replacing certain values in the params hash with "[FILTERED]" as they are written to the log. As an example, let’s see how to filter all parameters with keys that include "password":

filter_parameter_logging :password -end -

The method works recursively through all levels of the params hash and takes an optional second parameter which is used as the replacement string if present. It can also take a block which receives each key in turn and replaces those for which the block returns true.

+end

13. Rescue

Most likely your application is going to contain bugs or otherwise throw an exception that needs to be handled. For example, if the user follows a link to a resource that no longer exists in the database, Active Record will throw the ActiveRecord::RecordNotFound exception. Rails' default exception handling displays a 500 Server Error message for all exceptions. If the request was made locally, a nice traceback and some added information gets displayed so you can figure out what went wrong and deal with it. If the request was remote Rails will just display a simple "500 Server Error" message to the user, or a "404 Not Found" if there was a routing error or a record could not be found. Sometimes you might want to customize how these errors are caught and how they're displayed to the user. There are several levels of exception handling available in a Rails application:

Most likely your application is going to contain bugs or otherwise throw an exception that needs to be handled. For example, if the user follows a link to a resource that no longer exists in the database, Active Record will throw the ActiveRecord::RecordNotFound exception. Rails' default exception handling displays a 500 Server Error message for all exceptions. If the request was made locally, a nice traceback and some added information gets displayed so you can figure out what went wrong and deal with it. If the request was remote Rails will just display a simple "500 Server Error" message to the user, or a "404 Not Found" if there was a routing error or a record could not be found. Sometimes you might want to customize how these errors are caught and how they’re displayed to the user. There are several levels of exception handling available in a Rails application:

13.1. The Default 500 and 404 Templates

By default a production application will render either a 404 or a 500 error message. These messages are contained in static HTML files in the public folder, in 404.html and 500.html respectively. You can customize these files to add some extra information and layout, but remember that they are static; i.e. you can't use RHTML or layouts in them, just plain HTML.

13.2. `rescue_from`

If you want to do something a bit more elaborate when catching errors, you can use rescue_from, which handles exceptions of a certain type (or multiple types) in an entire controller and its subclasses. When an exception occurs which is caught by a rescue_from directive, the exception object is passed to the handler. The handler can be a method or a Proc object passed to the :with option. You can also use a block directly instead of an explicit Proc object.

Here's how you can use rescue_from to intercept all ActiveRecord::RecordNotFound errors and do something with them.

Here’s how you can use rescue_from to intercept all ActiveRecord::RecordNotFound errors and do something with them.

+ + + + + + + +

+ + + +

Active Record Query Interface

This guide covers different ways to retrieve data from the database using Active Record. By referring to this guide, you will be able to:

+
+Find records using a variety of methods and conditions +
+
+
+Specify the order, retrieved attributes, grouping, and other properties of the found records +
+
+
+Use eager loading to reduce the number of database queries needed for data retrieval +
+
+
+Use dynamic finders methods +
+
+
+Create named scopes to add custom finding behavior to your models +
+
+
+Check for the existence of particular records +
+
+
+Perform various calculations on Active Record models +
+

If you’re used to using raw SQL to find database records then, generally, you will find that there are better ways to carry out the same operations in Rails. Active Record insulates you from the need to use SQL in most cases.

Code examples throughout this guide will refer to one or more of the following models:

class Client < ActiveRecord::Base
+  has_one :address
+  has_one :mailing_address
+  has_many :orders
+  has_and_belongs_to_many :roles
+end

class Address < ActiveRecord::Base
+  belongs_to :client
+end

class MailingAddress < Address
+end

class Order < ActiveRecord::Base
+  belongs_to :client, :counter_cache => true
+end

class Role < ActiveRecord::Base
+  has_and_belongs_to_many :clients
+end

Active Record will perform queries on the database for you and is compatible with most database systems (MySQL, PostgreSQL and SQLite to name a few). Regardless of which database system you’re using, the Active Record method format will always be the same.

1. Retrieving objects

To retrieve objects from the database, Active Record provides a primary method called find. This method allows you to pass arguments into it to perform certain queries on your database without the need of SQL. If you wanted to find the record with the id of 1, you could type Client.find(1) which would execute this query on your database:

SELECT * FROM clients WHERE (clients.id = 1)

+ + + +

+ +	Because this is a standard table created from a migration in Rails, the primary key is defaulted to id. If you have specified a different primary key in your migrations, this is what Rails will find on when you call the find method, not the id column.

If you wanted to find clients with id 1 or 2, you call Client.find([1,2]) or Client.find(1,2) and then this will be executed as:

SELECT * FROM clients WHERE (clients.id IN (1,2))

>> Client.find(1,2)
+=> [#<Client id: 1, name: => "Ryan", locked: false, orders_count: 2,
+  created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50">,
+  #<Client id: 2, name: => "Michael", locked: false, orders_count: 3,
+  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40">]

Note that if you pass in a list of numbers that the result will be returned as an array, not as a single Client object.

+ + + +

+ +	If `find(id)` or `find([id1, id2])` fails to find any records, it will raise a RecordNotFound exception.

If you wanted to find the first Client object you would simply type Client.first and that would find the first client in your clients table:

>> Client.first
+=> #<Client id: 1, name: => "Ryan", locked: false, orders_count: 2,
+  created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50">

If you were reading your log file (the default is log/development.log) you may see something like this:

SELECT * FROM clients LIMIT 1

Indicating the query that Rails has performed on your database.

To find the last Client object you would simply type Client.last and that would find the last client created in your clients table:

>> Client.last
+=> #<Client id: 2, name: => "Michael", locked: false, orders_count: 3,
+  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40">

If you were reading your log file (the default is log/development.log) you may see something like this:

SELECT * FROM clients ORDER BY id DESC LIMIT 1

+ + + +

+ + Please be aware that the syntax that Rails uses to find the first record in the table means that it may not be the actual first record. If you want the actual first record based on a field in your table (e.g. created_at) specify an order option in your find call. The last method call works differently: it finds the last record on your table based on the primary key column.

SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1

To find all the Client objects you would simply type Client.all and that would find all the clients in your clients table:

>> Client.all
+=> [#<Client id: 1, name: => "Ryan", locked: false, orders_count: 2,
+  created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50">,
+  #<Client id: 2, name: => "Michael", locked: false, orders_count: 3,
+  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40">]

You may see in Rails code that there are calls to methods such as Client.find(:all), Client.find(:first) and Client.find(:last). These methods are just alternatives to Client.all, Client.first and Client.last respectively.

Be aware that Client.first/Client.find(:first) and Client.last/Client.find(:last) will both return a single object, where as Client.all/Client.find(:all) will return an array of Client objects, just as passing in an array of ids to find will do also.

2. Conditions

The find method allows you to specify conditions to limit the records returned. You can specify conditions as a string, array, or hash.

2.1. Pure String Conditions

If you’d like to add conditions to your find, you could just specify them in there, just like Client.first(:conditions => "orders_count = 2"). This will find all clients where the orders_count field’s value is 2.

+ + + +

+ +	Building your own conditions as pure strings can leave you vulnerable to SQL injection exploits. For example, `Client.first(:conditions => "name LIKE %#{params[:name]}%")` is not safe. See the next section for the preferred way to handle conditions using an array.

2.2. Array Conditions

Now what if that number could vary, say as a argument from somewhere, or perhaps from the user’s level status somewhere? The find then becomes something like Client.first(:conditions => ["orders_count = ?", params[:orders]]). Active Record will go through the first element in the conditions value and any additional elements will replace the question marks (?) in the first element. If you want to specify two conditions, you can do it like Client.first(:conditions => ["orders_count = ? AND locked = ?", params[:orders], false]). In this example, the first question mark will be replaced with the value in params[:orders] and the second will be replaced with the SQL representation of false, which depends on the adapter.

The reason for doing code like:

Client.first(:conditions => ["orders_count = ?", params[:orders]])

instead of:

Client.first(:conditions => "orders_count = #{params[:orders]}")

is because of argument safety. Putting the variable directly into the conditions string will pass the variable to the database as-is. This means that it will be an unescaped variable directly from a user who may have malicious intent. If you do this, you put your entire database at risk because once a user finds out he or she can exploit your database they can do just about anything to it. Never ever put your arguments directly inside the conditions string.

+ + + +

+ +	For more information on the dangers of SQL injection, see the Ruby on Rails Security Guide.

If you’re looking for a range inside of a table (for example, users created in a certain timeframe) you can use the conditions option coupled with the IN sql statement for this. If you had two dates coming in from a controller you could do something like this to look for a range:

Client.all(:conditions => ["created_at IN (?)",
+  (params[:start_date].to_date)..(params[:end_date].to_date)])

This would generate the proper query which is great for small ranges but not so good for larger ranges. For example if you pass in a range of date objects spanning a year that’s 365 (or possibly 366, depending on the year) strings it will attempt to match your field against.

SELECT * FROM users WHERE (created_at IN
+  ('2007-12-31','2008-01-01','2008-01-02','2008-01-03','2008-01-04','2008-01-05',
+  '2008-01-06','2008-01-07','2008-01-08','2008-01-09','2008-01-10','2008-01-11',
+  '2008-01-12','2008-01-13','2008-01-14','2008-01-15','2008-01-16','2008-01-17',
+  '2008-01-18','2008-01-19','2008-01-20','2008-01-21','2008-01-22','2008-01-23',...
+  ‘2008-12-15','2008-12-16','2008-12-17','2008-12-18','2008-12-19','2008-12-20',
+  '2008-12-21','2008-12-22','2008-12-23','2008-12-24','2008-12-25','2008-12-26',
+  '2008-12-27','2008-12-28','2008-12-29','2008-12-30','2008-12-31'))

Things can get really messy if you pass in Time objects as it will attempt to compare your field to every second in that range:

Client.all(:conditions => ["created_at IN (?)",
+  (params[:start_date].to_date.to_time)..(params[:end_date].to_date.to_time)])

SELECT * FROM users WHERE (created_at IN
+  ('2007-12-01 00:00:00', '2007-12-01 00:00:01' ...
+  '2007-12-01 23:59:59', '2007-12-02 00:00:00'))

This could possibly cause your database server to raise an unexpected error, for example MySQL will throw back this error:

Got a packet bigger than 'max_allowed_packet' bytes: _query_

Where query is the actual query used to get that error.

In this example it would be better to use greater-than and less-than operators in SQL, like so:

Client.all(:conditions =>
+  ["created_at > ? AND created_at < ?", params[:start_date], params[:end_date]])

You can also use the greater-than-or-equal-to and less-than-or-equal-to like this:

Client.all(:conditions =>
+  ["created_at >= ? AND created_at <= ?", params[:start_date], params[:end_date]])

Just like in Ruby. If you want a shorter syntax be sure to check out the Hash Conditions section later on in the guide.

2.3. Placeholder Conditions

Similar to the array style of params you can also specify keys in your conditions:

Client.all(:conditions =>
+  ["created_at >= :start_date AND created_at <= :end_date", { :start_date => params[:start_date], :end_date => params[:end_date] }])

This makes for clearer readability if you have a large number of variable conditions.

2.4. Hash Conditions

Rails also allows you to pass in a hash conditions which can increase the readability of your conditions syntax. With hash conditions, you pass in a hash with keys of the fields you want conditionalised and the values of how you want to conditionalise them:

Client.all(:conditions => { :locked => true })

The field name does not have to be a symbol it can also be a string:

Client.all(:conditions => { 'locked' => true })

The good thing about this is that we can pass in a range for our fields without it generating a large query as shown in the preamble of this section.

Client.all(:conditions => { :created_at => (Time.now.midnight - 1.day)..Time.now.midnight})

This will find all clients created yesterday by using a BETWEEN sql statement:

SELECT * FROM `clients` WHERE (`clients`.`created_at` BETWEEN '2008-12-21 00:00:00' AND '2008-12-22 00:00:00')

This demonstrates a shorter syntax for the examples in Array Conditions

You can also join in tables and specify their columns in the hash:

Client.all(:include => "orders", :conditions => { 'orders.created_at' => (Time.now.midnight - 1.day)..Time.now.midnight })

An alternative and cleaner syntax to this is:

Client.all(:include => "orders", :conditions => { :orders => { :created_at => (Time.now.midnight - 1.day)..Time.now.midnight } })

This will find all clients who have orders that were created yesterday, again using a BETWEEN expression.

If you want to find records using the IN expression you can pass an array to the conditions hash:

Client.all(:include => "orders", :conditions => { :orders_count => [1,3,5] }

This code will generate SQL like this:

SELECT * FROM `clients` WHERE (`clients`.`orders_count` IN (1,2,3))

3. Ordering

If you’re getting a set of records and want to order them in ascending order by the created_at field in your table, you can use Client.all(:order => "created_at"). If you’d like to order it in descending order, just tell it to do that using Client.all(:order => "created_at desc"). The value for this option is passed in as sanitized SQL and allows you to sort via multiple fields: Client.all(:order => "created_at desc, orders_count asc").

4. Selecting Certain Fields

To select certain fields, you can use the select option like this: Client.first(:select => "viewable_by, locked"). This select option does not use an array of fields, but rather requires you to type SQL-like code. The above code will execute SELECT viewable_by, locked FROM clients LIMIT 1 on your database.

Be careful because this also means you’re initializing a model object with only the fields that you’ve selected. If you attempt to access a field that is not in the initialized record you’ll receive:

ActiveRecord::MissingAttributeError: missing attribute: <attribute>

Where <attribute> is the atrribute you asked for. The id method will not raise the ActiveRecord::MissingAttributeError, so just be careful when working with associations because they need the id method to function properly.

You can also call SQL functions within the select option. For example, if you would like to only grab a single record per unique value in a certain field by using the DISTINCT function you can do it like this: Client.all(:select => "DISTINCT(name)").

5. Limit & Offset

If you want to limit the amount of records to a certain subset of all the records retrieved you usually use limit for this, sometimes coupled with offset. Limit is the maximum number of records that will be retrieved from a query, and offset is the number of records it will start reading from from the first record of the set. Take this code for example:

Client.all(:limit => 5)

This code will return a maximum of 5 clients and because it specifies no offset it will return the first 5 clients in the table. The SQL it executes will look like this:

SELECT * FROM clients LIMIT 5

Client.all(:limit => 5, :offset => 5)

This code will return a maximum of 5 clients and because it specifies an offset this time, it will return these records starting from the 5th client in the clients table. The SQL looks like:

SELECT * FROM clients LIMIT 5, 5

6. Group

The group option for find is useful, for example, if you want to find a collection of the dates orders were created on. You could use the option in this context:

Order.all(:group => "date(created_at)", :order => "created_at")

And this will give you a single Order object for each date where there are orders in the database.

The SQL that would be executed would be something like this:

SELECT * FROM orders GROUP BY date(created_at)

7. Having

The :having option allows you to specify SQL and acts as a kind of a filter on the group option. :having can only be specified when :group is specified.

An example of using it would be:

Order.all(:group => "date(created_at)", :having => ["created_at > ?", 1.month.ago])

This will return single order objects for each day, but only for the last month.

8. Read Only

readonly is a find option that you can set in order to make that instance of the record read-only. Any attempt to alter or destroy the record will not succeed, raising an ActiveRecord::ReadOnlyRecord exception. To set this option, specify it like this:

Client.first(:readonly => true)

If you assign this record to a variable client, calling the following code will raise an ActiveRecord::ReadOnlyRecord exception:

client = Client.first(:readonly => true)
+client.locked = false
+client.save

9. Lock

If you’re wanting to stop race conditions for a specific record (for example, you’re incrementing a single field for a record, potentially from multiple simultaneous connections) you can use the lock option to ensure that the record is updated correctly. For safety, you should use this inside a transaction.

Topic.transaction do
+  t = Topic.find(params[:id], :lock => true)
+  t.increment!(:views)
+end

You can also pass SQL to this option to allow different types of locks. For example, MySQL has an expression called LOCK IN SHARE MODE where you can lock a record but still allow other queries to read it. To specify this expression just pass it in as the lock option:

Topic.transaction do
+  t = Topic.find(params[:id], :lock => "LOCK IN SHARE MODE")
+  t.increment!(:views)
+end

10. Making It All Work Together

You can chain these options together in no particular order as Active Record will write the correct SQL for you. If you specify two instances of the same options inside the find method Active Record will use the last one you specified. This is because the options passed to find are a hash and defining the same key twice in a hash will result in the last definition being used.

11. Eager Loading

Eager loading is loading associated records along with any number of records in as few queries as possible. For example, if you wanted to load all the addresses associated with all the clients in a single query you could use Client.all(:include => :address). If you wanted to include both the address and mailing address for the client you would use Client.find(:all, :include => [:address, :mailing_address]). Include will first find the client records and then load the associated address records. Running script/server in one window, and executing the code through script/console in another window, the output should look similar to this:

Client Load (0.000383)   SELECT * FROM clients
+Address Load (0.119770)   SELECT addresses.* FROM addresses
+  WHERE (addresses.client_id IN (13,14))
+MailingAddress Load (0.001985) SELECT mailing_addresses.* FROM
+  mailing_addresses WHERE (mailing_addresses.client_id IN (13,14))

The numbers 13 and 14 in the above SQL are the ids of the clients gathered from the Client.all query. Rails will then run a query to gather all the addresses and mailing addresses that have a client_id of 13 or 14. Although this is done in 3 queries, this is more efficient than not eager loading because without eager loading it would run a query for every time you called address or mailing_address on one of the objects in the clients array, which may lead to performance issues if you’re loading a large number of records at once and is often called the "N+1 query problem". The problem is that the more queries your server has to execute, the slower it will run.

If you wanted to get all the addresses for a client in the same query you would do Client.all(:joins => :address). +If you wanted to find the address and mailing address for that client you would do Client.all(:joins => [:address, :mailing_address]). This is more efficient because it does all the SQL in one query, as shown by this example:

+Client Load (0.000455)   SELECT clients.* FROM clients INNER JOIN addresses
+  ON addresses.client_id = client.id INNER JOIN mailing_addresses ON
+  mailing_addresses.client_id = client.id

This query is more efficent, but there’s a gotcha: if you have a client who does not have an address or a mailing address they will not be returned in this query at all. If you have any association as an optional association, you may want to use include rather than joins. Alternatively, you can use a SQL join clause to specify exactly the join you need (Rails always assumes an inner join):

Client.all(:joins => “LEFT OUTER JOIN addresses ON
+  client.id = addresses.client_id LEFT OUTER JOIN mailing_addresses ON
+  client.id = mailing_addresses.client_id”)

When using eager loading you can specify conditions for the columns of the tables inside the eager loading to get back a smaller subset. If, for example, you want to find a client and all their orders within the last two weeks you could use eager loading with conditions for this:

Client.first(:include => "orders", :conditions =>
+  ["orders.created_at >= ? AND orders.created_at <= ?", 2.weeks.ago, Time.now])

12. Dynamic finders

For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called name on your Client model for example, you get find_by_name and find_all_by_name for free from Active Record. If you have also have a locked field on the Client model, you also get find_by_locked and find_all_by_locked.

You can do find_last_by_* methods too which will find the last record matching your argument.

You can specify an exclamation point (!) on the end of the dynamic finders to get them to raise an ActiveRecord::RecordNotFound error if they do not return any records, like Client.find_by_name!("Ryan")

If you want to find both by name and locked, you can chain these finders together by simply typing and between the fields for example Client.find_by_name_and_locked("Ryan", true).

There’s another set of dynamic finders that let you find or create/initialize objects if they aren’t found. These work in a similar fashion to the other finders and can be used like find_or_create_by_name(params[:name]). Using this will firstly perform a find and then create if the find returns nil. The SQL looks like this for Client.find_or_create_by_name("Ryan"):

SELECT * FROM clients WHERE (clients.name = 'Ryan') LIMIT 1
+BEGIN
+INSERT INTO clients (name, updated_at, created_at, orders_count, locked)
+  VALUES('Ryan', '2008-09-28 15:39:12', '2008-09-28 15:39:12', 0, '0')
+COMMIT

find_or_create's sibling, find_or_initialize, will find an object and if it does not exist will act similar to calling new with the arguments you passed in. For example:

client = Client.find_or_initialize_by_name('Ryan')

will either assign an existing client object with the name Ryan to the client local variable, or initialize a new object similar to calling Client.new(:name => Ryan). From here, you can modify other fields in client by calling the attribute setters on it: client.locked = true and when you want to write it to the database just call save on it.

13. Finding By SQL

If you’d like to use your own SQL to find records in a table you can use find_by_sql. The find_by_sql method will return an array of objects even the underlying query returns just a single record. For example you could run this query:

Client.find_by_sql("SELECT * FROM clients INNER JOIN orders ON clients.id = orders.client_id ORDER clients.created_at desc")

find_by_sql provides you with a simple way of making custom calls to the database and retrieving instantiated objects.

14. `select_all`

find_by_sql has a close relative called connection#select_all. select_all will retrieve objects from the database using custom SQL just like find_by_sql but will not instantiate them. Instead, you will get an array of hashes where each hash indicates a record.

Client.connection.select_all("SELECT * FROM `clients` WHERE `id` = '1'")

15. Working with Associations

When you define a has_many association on a model you get the find method and dynamic finders also on that association. This is helpful for finding associated records within the scope of an existing record, for example finding all the orders for a client that have been sent and not received by doing something like Client.find(params[:id]).orders.find_by_sent_and_received(true, false). Having this find method available on associations is extremely helpful when using nested resources.

16. Named Scopes

Named scopes are another way to add custom finding behavior to the models in the application. Named scopes provide an object-oriented way to narrow the results of a query.

16.1. Simple Named Scopes

Suppose we want to find all clients who are male. You could use this code:

class Client < ActiveRecord::Base
+  named_scope :males, :conditions => { :gender => "male" }
+end

Then you could call Client.males.all to get all the clients who are male. Please note that if you do not specify the all on the end you will get a Scope object back, not a set of records which you do get back if you put the all on the end.

If you wanted to find all the clients who are active, you could use this:

class Client < ActiveRecord::Base
+  named_scope :active, :conditions => { :active => true }
+end

You can call this new named_scope with Client.active.all and this will do the same query as if we just used Client.all(:conditions => ["active = ?", true]). If you want to find the first client within this named scope you could do Client.active.first.

16.2. Combining Named Scopes

If you wanted to find all the clients who are active and male you can stack the named scopes like this:

Client.males.active.all

If you would then like to do a all on that scope, you can. Just like an association, named scopes allow you to call all on them:

Client.males.active.all(:conditions => ["age > ?", params[:age]])

16.3. Runtime Evaluation of Named Scope Conditions

Consider the following code:

class Client < ActiveRecord::Base
+  named_scope :recent, :conditions => { :created_at > 2.weeks.ago }
+end

This looks like a standard named scope that defines a method called recent which gathers all records created any time between now and 2 weeks ago. That’s correct for the first time the model is loaded but for any time after that, 2.weeks.ago is set to that same value, so you will consistently get records from a certain date until your model is reloaded by something like your application restarting. The way to fix this is to put the code in a lambda block:

class Client < ActiveRecord::Base
+  named_scope :recent, lambda { { :conditions => ["created_at > ?", 2.weeks.ago] } }
+end

And now every time the recent named scope is called, the code in the lambda block will be executed, so you’ll get actually 2 weeks ago from the code execution, not 2 weeks ago from the time the model was loaded.

16.4. Named Scopes with Multiple Models

In a named scope you can use :include and :joins options just like in find.

class Client < ActiveRecord::Base
+  named_scope :active_within_2_weeks, :joins => :order,
+    lambda { { :conditions => ["orders.created_at > ?", 2.weeks.ago] } }
+end

This method, called as Client.active_within_2_weeks.all, will return all clients who have placed orders in the past 2 weeks.

16.5. Arguments to Named Scopes

If you want to pass to a named scope a required arugment, just specify it as a block argument like this:

class Client < ActiveRecord::Base
+  named_scope :recent, lambda { |time| { :conditions => ["created_at > ?", time] } }
+end

This will work if you call Client.recent(2.weeks.ago).all but not if you call Client.recent. If you want to add an optional argument for this, you have to use prefix the arugment with an *.

class Client < ActiveRecord::Base
+  named_scope :recent, lambda { |*args| { :conditions => ["created_at > ?", args.first || 2.weeks.ago] } }
+end

This will work with Client.recent(2.weeks.ago).all and Client.recent.all, with the latter always returning records with a created_at date between right now and 2 weeks ago.

Remember that named scopes are stackable, so you will be able to do Client.recent(2.weeks.ago).unlocked.all to find all clients created between right now and 2 weeks ago and have their locked field set to false.

16.6. Anonymous Scopes

All Active Record models come with a named scope named scoped, which allows you to create anonymous scopes. For example:

class Client < ActiveRecord::Base
+  def self.recent
+    scoped :conditions => ["created_at > ?", 2.weeks.ago]
+  end
+end

Anonymous scopes are most useful to create scopes "on the fly":

Client.scoped(:conditions => { :gender => "male" })

Just like named scopes, anonymous scopes can be stacked, either with other anonymous scopes or with regular named scopes.

17. Existence of Objects

If you simply want to check for the existence of the object there’s a method called exists?. This method will query the database using the same query as find, but instead of returning an object or collection of objects it will return either true or false+.

Client.exists?(1)

The exists? method also takes multiple ids, but the catch is that it will return true if any one of those records exists.

Client.exists?(1,2,3)
+# or
+Client.exists?([1,2,3])

Further more, exists takes a conditions option much like find:

Client.exists?(:conditions => "first_name = 'Ryan'")

18. Calculations

This section uses count as an example method in this preamble, but the options described apply to all sub-sections.

count takes conditions much in the same way exists? does:

Client.count(:conditions => "first_name = 'Ryan'")

Which will execute:

SELECT count(*) AS count_all FROM clients WHERE (first_name = 'Ryan')

You can also use :include or :joins for this to do something a little more complex:

Client.count(:conditions => "clients.first_name = 'Ryan' AND orders.status = 'received'", :include => "orders")

Which will execute:

SELECT count(DISTINCT clients.id) AS count_all FROM clients
+  LEFT OUTER JOIN orders ON orders.client_id = client.id WHERE
+  (clients.first_name = 'Ryan' AND orders.status = 'received')

This code specifies clients.first_name just in case one of the join tables has a field also called first_name and it uses orders.status because that’s the name of our join table.

18.1. Count

If you want to see how many records are in your model’s table you could call Client.count and that will return the number. If you want to be more specific and find all the clients with their age present in the database you can use Client.count(:age).

For options, please see the parent section, Calculations.

18.2. Average

If you want to see the average of a certain number in one of your tables you can call the average method on the class that relates to the table. This method call will look something like this:

Client.average("orders_count")

This will return a number (possibly a floating point number such as 3.14159265) representing the average value in the field.

For options, please see the parent section, Calculations.

18.3. Minimum

If you want to find the minimum value of a field in your table you can call the minimum method on the class that relates to the table. This method call will look something like this:

Client.minimum("age")

For options, please see the parent section, Calculations

18.4. Maximum

If you want to find the maximum value of a field in your table you can call the maximum method on the class that relates to the table. This method call will look something like this:

Client.maximum("age")

For options, please see the parent section, Calculations

18.5. Sum

If you want to find the sum of a field for all records in your table you can call the sum method on the class that relates to the table. This method call will look something like this:

Client.sum("orders_count")

For options, please see the parent section, Calculations

19. Changelog

Lighthouse ticket

+
+December 29 2008: Initial version by Ryan Bigg +
+

+ +

+ + diff --git a/railties/doc/guides/html/activerecord_validations_callbacks.html b/railties/doc/guides/html/activerecord_validations_callbacks.html index 039e3d1891..be556283c1 100644 --- a/railties/doc/guides/html/activerecord_validations_callbacks.html +++ b/railties/doc/guides/html/activerecord_validations_callbacks.html @@ -1,334 +1,185 @@ - - Active Record Validations and Callbacks - - - - - + + Active Record Validations and Callbacks + + + + - -

- - - -

Active Record Validations and Callbacks

+ + + +

Active Record Validations and Callbacks

This guide teaches you how to work with the lifecycle of your Active Record objects. More precisely, you will learn how to validate the state of your objects before they go into the database and also how to teach them to perform custom operations at certain points of their lifecycles.

After reading this guide and trying out the presented concepts, we hope that you'll be able to:

This guide teaches you how to hook into the lifecycle of your Active Record objects. More precisely, you will learn how to validate the state of your objects before they go into the database as well as how to perform custom operations at certain points in the object lifecycle.

After reading this guide and trying out the presented concepts, we hope that you’ll be able to:

-Correctly use all the built-in Active Record validation helpers +Use the built-in Active Record validation helpers
@@ -343,57 +194,55 @@ Work with the error messages generated by the validation process
-Register callback methods that will execute custom operations during your objects lifecycle, for example before/after they are saved. +Create callback methods to respond to events in the object lifecycle.
-Create special classes that encapsulate common behaviour for your callbacks +Create special classes that encapsulate common behavior for your callbacks
-Create Observers - classes with callback methods specific for each of your models, keeping the callback code outside your models' declarations. +Create Rails Observers

1. Motivations to validate your Active Record objects

1. Overview of ActiveRecord Validation

The main reason for validating your objects before they get into the database is to ensure that only valid data is recorded. It's important to be sure that an email address column only contains valid email addresses, or that the customer's name column will never be empty. Constraints like that keep your database organized and helps your application to work properly.

There are several ways to validate the data that goes to the database, like using database native constraints, implementing validations only at the client side or implementing them directly into your models. Each one has pros and cons:

Before you dive into the detail of validations in Rails, you should understand a bit about how validations fit into the big picture. Why should you use validations? When do these validations take place?

1.1. Why Use ActiveRecord Validations?

The main reason for validating your objects before they get into the database is to ensure that only valid data is recorded. It’s important to be sure that an email address column only contains valid email addresses, or that the customer’s name column will never be empty. Constraints like that keep your database organized and helps your application to work properly.

There are several ways that you could validate the data that goes to the database, including native database constraints, client-side validations, and model-level validations. Each of these has pros and cons:

-Using database constraints and/or stored procedures makes the validation mechanisms database-dependent and may turn your application into a hard to test and mantain beast. However, if your database is used by other applications, it may be a good idea to use some constraints also at the database level. +Using database constraints and/or stored procedures makes the validation mechanisms database-dependent and may turn your application into a hard to test and maintain beast. However, if your database is used by other applications, it may be a good idea to use some constraints also at the database level. Additionally, database-level validations can safely handle some things (such as uniqueness in heavily-used tables) that are problematic to implement from the application level.
-Implementing validations only at the client side can be problematic, specially with web-based applications. Usually this kind of validation is done using javascript, which may be turned off in the user's browser, leading to invalid data getting inside your database. However, if combined with server side validation, client side validation may be useful, since the user can have a faster feedback from the application when trying to save invalid data. +Implementing validations only at the client side can be difficult in web-based applications. Usually this kind of validation is done using javascript, which may be turned off in the user’s browser, leading to invalid data getting inside your database. However, if combined with server side validation, client side validation may be useful, since the user can have a faster feedback from the application when trying to save invalid data.
-Using validation directly into your Active Record classes ensures that only valid data gets recorded, while still keeping the validation code in the right place, avoiding breaking the MVC pattern. Since the validation happens on the server side, the user cannot disable it, so it's also safer. It may be a hard and tedious work to implement some of the logic involved in your models' validations, but fear not: Active Record gives you the hability to easily create validations, using several built-in helpers while still allowing you to create your own validation methods. +Using validation directly in your Active Record classes ensures that only valid data gets recorded, while still keeping the validation code in the right place, avoiding breaking the MVC pattern. Since the validation happens on the server side, the user cannot disable it, so it’s also safer. It may be a hard and tedious work to implement some of the logic involved in your models' validations, but fear not: Active Record gives you the ability to easily create validations, providing built-in helpers for common validations while still allowing you to create your own validation methods.

2. How it works

2.1. When does validation happens?

There are two kinds of Active Record objects: those that correspond to a row inside your database and those who do not. When you create a fresh object, using the new method, that object does not belong to the database yet. Once you call save upon that object it'll be recorded to it's table. Active Record uses the new_record? instance method to discover if an object is already in the database or not. Consider the following simple and very creative Active Record class:

1.2. When Does Validation Happen?

There are two kinds of Active Record objects: those that correspond to a row inside your database and those that do not. When you create a fresh object, using the new method, that object does not belong to the database yet. Once you call save upon that object it will be saved into the appropriate database table. Active Record uses the new_record? instance method to determine whether an object is already in the database or not. Consider the following simple Active Record class:

class Person < ActiveRecord::Base
-end
-

We can see how it works by looking at the following script/console output:

+end

We can see how it works by looking at some script/console output:

>> p = Person.new(:name => "John Doe", :birthdate => Date.parse("09/03/1979"))
@@ -405,25 +254,25 @@ http://www.gnu.org/software/src-highlite -->
 >> p.new_record?
 => false

Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either save or update_attributes) will result in a SQL update operation. Active Record will use these facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.

Saving new records means sending an SQL INSERT operation to the database, while saving existing records (by calling either save or update_attributes) will result in a SQL UPDATE operation. Active Record will use these facts to perform validations upon your objects, keeping them out of the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you’re creating a new record or when you’re updating an existing one.

- +

There are four methods that when called will trigger validation: save, save!, update_attributes and update_attributes!. There is one method left, which is update_attribute. This method will update the value of an attribute without triggering any validation, so be careful when using update_attribute, since it can let you save your objects in an invalid state. There are four methods that when called will trigger validation: save, save!, update_attributes and update_attributes!. There is one update method for Active Record objects left, which is update_attribute. This method will update the value of an attribute without triggering any validation. Be careful when using update_attribute, because it can let you save your objects in an invalid state.

2.2. The meaning of valid

For verifying if an object is valid, Active Record uses the valid? method, which basically looks inside the object to see if it has any validation errors. These errors live in a collection that can be accessed through the errors instance method. The proccess is really simple: If the errors method returns an empty collection, the object is valid and can be saved. Each time a validation fails, an error message is added to the errors collection.

1.3. The Meaning of `valid`

To verify whether an object is valid, Active Record uses the valid? method, which basically looks inside the object to see if it has any validation errors. These errors live in a collection that can be accessed through the errors instance method. The process is really simple: If the errors method returns an empty collection, the object is valid and can be saved. Each time a validation fails, an error message is added to the errors collection.

3. The declarative validation helpers

2. The Declarative Validation Helpers

Active Record offers many pre-defined validation helpers that you can use directly inside your class definitions. These helpers create validations rules that are commonly used in most of the applications that you'll write, so you don't need to recreate it everytime, avoiding code duplication, keeping everything organized and boosting your productivity. Everytime a validation fails, an error message is added to the object's errors collection, this message being associated with the field being validated.

Each helper accepts an arbitrary number of attributes, received as symbols, so with a single line of code you can add the same kind of validation to several attributes.

All these helpers accept the :on and :message options, which define when the validation should be applied and what message should be added to the errors collection when it fails, respectively. The :on option takes one the values :save (it's the default), :create or :update. There is a default error message for each one of the validation helpers. These messages are used when the :message option isn't used. Let's take a look at each one of the available helpers, listed in alphabetic order.

3.1. The `validates_acceptance_of` helper

Validates that a checkbox has been checked for agreement purposes. It's normally used when the user needs to agree with your application's terms of service, confirm reading some clauses or any similar concept. This validation is very specific to web applications and actually this acceptance does not need to be recorded anywhere in your database (if you don't have a field for it, the helper will just create a virtual attribute).

Active Record offers many pre-defined validation helpers that you can use directly inside your class definitions. These helpers create validation rules that are commonly used. Every time a validation fails, an error message is added to the object’s errors collection, and this message is associated with the field being validated.

Each helper accepts an arbitrary number of attributes identified by symbols, so with a single line of code you can add the same kind of validation to several attributes.

All these helpers accept the :on and :message options, which define when the validation should be applied and what message should be added to the errors collection when it fails, respectively. The :on option takes one of the values :save (the default), :create or :update. There is a default error message for each one of the validation helpers. These messages are used when the :message option isn’t used. Let’s take a look at each one of the available helpers.

2.1. The `validates_acceptance_of` helper

Validates that a checkbox on the user interface was checked when a form was submitted. This is normally used when the user needs to agree to your application’s terms of service, confirm reading some text, or any similar concept. This validation is very specific to web applications and actually this acceptance does not need to be recorded anywhere in your database (if you don’t have a field for it, the helper will just create a virtual attribute).

class Person < ActiveRecord::Base
   validates_acceptance_of :terms_of_service
-end
-

The default error message for validates_acceptance_of is "must be accepted"

validates_acceptance_of can receive an :accept option, which determines the value that will be considered acceptance. It defaults to "1", but you can change it.

+end

The default error message for validates_acceptance_of is "must be accepted"

validates_acceptance_of can receive an :accept option, which determines the value that will be considered acceptance. It defaults to "1", but you can change this.

class Person < ActiveRecord::Base
   validates_acceptance_of :terms_of_service, :accept => 'yes'
-end
-

3.2. The `validates_associated` helper

You should use this helper when your model has associations with other models and they also need to be validated. When you try to save your object, valid? will be called upon each one of the associated objects.

+end

2.2. The `validates_associated` helper

class Library < ActiveRecord::Base
   has_many :books
   validates_associated :books
-end
-

This validation will work with all the association types.

+end

This validation will work with all the association types.

- +

Pay attention not to use validates_associated on both ends of your associations, because this will lead to several recursive calls and blow up the method calls' stack. Don’t use validates_associated on both ends of your associations, because this will lead to several recursive calls and blow up the method calls' stack.

The default error message for validates_associated is "is invalid". Note that the errors for each failed validation in the associated objects will be set there and not in this model.

3.3. The `validates_confirmation_of` helper

You should use this helper when you have two text fields that should receive exactly the same content, like when you want to confirm an email address or password. This validation creates a virtual attribute, using the name of the field that has to be confirmed with _confirmation appended.

The default error message for validates_associated is "is invalid". Note that each associated object will contain its own errors collection; errors do not bubble up to the calling model.

2.3. The `validates_confirmation_of` helper

You should use this helper when you have two text fields that should receive exactly the same content. For example, you may want to confirm an email address or a password. This validation creates a virtual attribute, using the name of the field that has to be confirmed with _confirmation appended.

class Person < ActiveRecord::Base
   validates_confirmation_of :email
-end
-

In your view template you could use something like

+end

In your view template you could use something like

<%= text_field :person, :email %>
-<%= text_field :person, :email_confirmation %>

+<%= text_field :person, :email_confirmation %>

- +

This check is performed only if email_confirmation is not nil, and by default only on save. To require confirmation, make sure to add a presence check for the confirmation attribute (we'll take a look at validates_presence_of later on this guide): This check is performed only if email_confirmation is not nil, and by default only on save. To require confirmation, make sure to add a presence check for the confirmation attribute (we’ll take a look at validates_presence_of later on this guide):

@@ -499,25 +346,10 @@ http://www.gnu.org/software/src-highlite -->

class Person < ActiveRecord::Base
   validates_confirmation_of :email
   validates_presence_of :email_confirmation
-end
-

The default error message for validates_confirmation_of is "doesn't match confirmation"

3.4. The `validates_each` helper

This helper validates attributes against a block. It doesn't have a predefined validation function. You should create one using a block, and every attribute passed to validates_each will be tested against it. In the following example, we don't want names and surnames to begin with lower case.

class Person < ActiveRecord::Base
-  validates_each :name, :surname do |model, attr, value|
-    model.errors.add(attr, 'Must start with upper case') if value =~ /^[a-z]/
-  end
-end
-

The block receives the model, the attribute's name and the attribute's value. If your validation fails, you can add an error message to the model, therefore making it invalid.

3.5. The `validates_exclusion_of` helper

This helper validates that the attributes' values are not included in a given set. In fact, this set can be any enumerable object.

+end +

The default error message for validates_confirmation_of is "doesn’t match confirmation"

2.4. The `validates_exclusion_of` helper

This helper validates that the attributes' values are not included in a given set. In fact, this set can be any enumerable object.

class MovieFile < ActiveRecord::Base
   validates_exclusion_of :format, :in => %w(mov avi),
     :message => "Extension %s is not allowed"
-end
-

The validates_exclusion_of helper has an option :in that receives the set of values that will not be accepted for the validated attributes. The :in option has an alias called :within that you can use for the same purpose, if you'd like to. In the previous example we used the :message option to show how we can personalize it with the current attribute's value, through the %s format mask.

The default error message for validates_exclusion_of is "is not included in the list".

3.6. The `validates_format_of` helper

This helper validates the attributes's values by testing if they match a given pattern. This pattern must be specified using a Ruby regular expression, which must be passed through the :with option.

+end +

The validates_exclusion_of helper has an option :in that receives the set of values that will not be accepted for the validated attributes. The :in option has an alias called :within that you can use for the same purpose, if you’d like to. This example uses the :message option to show how you can personalize it with the current attribute’s value, through the %s format mask.

The default error message for validates_exclusion_of is "is not included in the list".

2.5. The `validates_format_of` helper

This helper validates the attributes' values by testing whether they match a given pattern. This pattern must be specified using a Ruby regular expression, which is specified using the :with option.

class Product < ActiveRecord::Base
   validates_format_of :description, :with => /^[a-zA-Z]+$/,
     :message => "Only letters allowed"
-end
-

The default error message for validates_format_of is "is invalid".

3.7. The `validates_inclusion_of` helper

This helper validates that the attributes' values are included in a given set. In fact, this set can be any enumerable object.

+end +

The default error message for validates_format_of is "is invalid".

2.6. The `validates_inclusion_of` helper

This helper validates that the attributes' values are included in a given set. In fact, this set can be any enumerable object.

class Coffee < ActiveRecord::Base
   validates_inclusion_of :size, :in => %w(small medium large),
     :message => "%s is not a valid size"
-end
-

The validates_inclusion_of helper has an option :in that receives the set of values that will be accepted. The :in option has an alias called :within that you can use for the same purpose, if you'd like to. In the previous example we used the :message option to show how we can personalize it with the current attribute's value, through the %s format mask.

The default error message for validates_inclusion_of is "is not included in the list".

3.8. The `validates_length_of` helper

This helper validates the length of your attribute's value. It can receive a variety of different options, so you can specify length contraints in different ways.

+end +

The validates_inclusion_of helper has an option :in that receives the set of values that will be accepted. The :in option has an alias called :within that you can use for the same purpose, if you’d like to. The previous example uses the :message option to show how you can personalize it with the current attribute’s value, through the %s format mask.

The default error message for validates_inclusion_of is "is not included in the list".

2.7. The `validates_length_of` helper

This helper validates the length of your attribute’s value. It includes a variety of different options, so you can specify length constraints in different ways:

validates_length_of :bio, :maximum => 500 validates_length_of :password, :in => 6..20 validates_length_of :registration_number, :is => 6 -end -

The possible length constraint options are:

end

The possible length constraint options are:

:minimum - The attribute cannot have less than the specified length. @@ -594,7 +422,7 @@ http://www.gnu.org/software/src-highlite -->

The default error messages depend on the type of length validation being performed. You can personalize these messages, using the :wrong_length, :too_long and :too_short options and the %d format mask as a placeholder for the number corresponding to the length contraint being used. You can still use the :message option to specify an error message.

The default error messages depend on the type of length validation being performed. You can personalize these messages, using the :wrong_length, :too_long and :too_short options and the %d format mask as a placeholder for the number corresponding to the length constraint being used. You can still use the :message option to specify an error message.

class Person < ActiveRecord::Base
   validates_length_of :bio, :too_long => "you're writing too much. %d characters is the maximum allowed."
-end
-

This helper has an alias called validates_size_of, it's the same helper with a different name. You can use it if you'd like to.

3.9. The `validates_numericality_of` helper

This helper validates that your attributes have only numeric values. By default, it will match an optional sign followed by a integral or floating point number. Using the :integer_only option set to true, you can specify that only integral numbers are allowed.

If you use :integer_only set to true, then it will use the /\A[+\-]?\d+\Z/ regular expression to validate the attribute's value. Otherwise, it will try to convert the value using Kernel.Float.

+end +

The validates_size_of helper is an alias for validates_length_of.

2.8. The `validates_numericality_of` helper

If you set :integer_only to true, then it will use the $$/\A[\-]?\d+\Z/ regular expression to validate the attribute’s value. Otherwise, it will try to convert the value to a number using +Kernel.Float.

class Player < ActiveRecord::Base
   validates_numericality_of :points
-  validates_numericality_of :games_played, :integer_only => true
-end
-

The default error message for validates_numericality_of is "is not a number".

3.10. The `validates_presence_of` helper

This helper validates that the attributes are not empty. It uses the blank? method to check if the value is either nil or an empty string (if the string has only spaces, it will still be considered empty).

+ validates_numericality_of :games_played, :only_integer => true +end +

Besides :only_integer, the validates_numericality_of helper also accepts the following options to add constraints to acceptable values:

+
+:greater_than - Specifies the value must be greater than the supplied value. The default error message for this option is "must be greater than (value)" +
+
+
+:greater_than_or_equal_to - Specifies the value must be greater than or equal the supplied value. The default error message for this option is "must be greater than or equal to (value)" +
+
+
+:equal_to - Specifies the value must be equal to the supplied value. The default error message for this option is "must be equal to (value)" +
+
+
+:less_than - Specifies the value must be less than the supplied value. The default error message for this option is "must e less than (value)" +
+
+
+:less_than_or_equal_to - Specifies the value must be less than or equal the supplied value. The default error message for this option is "must be less or equal to (value)" +
+
+
+:odd - Specifies the value must be an odd number if set to true. The default error message for this option is "must be odd" +
+
+
+:even - Specifies the value must be an even number if set to true. The default error message for this option is "must be even" +
+

The default error message for validates_numericality_of is "is not a number".

2.9. The `validates_presence_of` helper

This helper validates that the specified attributes are not empty. It uses the blank? method to check if the value is either nil or an empty string (if the string has only spaces, it will still be considered empty).

class Person < ActiveRecord::Base
   validates_presence_of :name, :login, :email
-end
-

+end

- +

If you want to be sure that an association is present, you'll need to test if the foreign key used to map the association is present, and not the associated object itself.

If you want to be sure that an association is present, you’ll need to test whether the foreign key used to map the association is present, and not the associated object itself.

@@ -646,19 +509,18 @@ http://www.gnu.org/software/src-highlite -->

class LineItem < ActiveRecord::Base
   belongs_to :order
   validates_presence_of :order_id
-end
-

+end

- +

If you want to validate the presence of a boolean field (where the real values are true and false), you will want to use validates_inclusion_of :field_name, :in ⇒ [true, false] This is due to the way Object#blank? handles boolean values. false.blank? # ⇒ true

If you want to validate the presence of a boolean field (where the real values are true and false), you should use validates_inclusion_of :field_name, :in => [true, false] This is due to the way Object#blank? handles boolean values. false.blank? # => true

The default error message for validates_presence_of is "can't be empty".

3.11. The `validates_uniqueness_of` helper

This helper validates that the attribute's value is unique right before the object gets saved. It does not create a uniqueness constraint directly into your database, so it may happen that two different database connections create two records with the same value for a column that you wish were unique. To avoid that, you must create an unique index in your database.

The default error message for validates_presence_of is "can’t be empty".

2.10. The `validates_uniqueness_of` helper

This helper validates that the attribute’s value is unique right before the object gets saved. It does not create a uniqueness constraint directly into your database, so it may happen that two different database connections create two records with the same value for a column that you intend to be unique. To avoid that, you must create an unique index in your database.

class Account < ActiveRecord::Base
   validates_uniqueness_of :email
-end
-

The validation happens by performing a SQL query into the model's table, searching for a record where the attribute that must be validated is equal to the value in the object being validated.

There is a :scope option that you can use to specify other attributes that must be used to define uniqueness:

+end +

The validation happens by performing a SQL query into the model’s table, searching for a record where the attribute that must be validated is equal to the value in the object being validated.

There is a :scope option that you can use to specify other attributes that are used to limit the uniqueness check:

class Holiday < ActiveRecord::Base
   validates_uniqueness_of :name, :scope => :year,
     :message => "Should happen once per year"
-end
-

There is also a :case_sensitive option that you can use to define if the uniqueness contraint will be case sensitive or not. This option defaults to true.

+end +

There is also a :case_sensitive option that you can use to define whether the uniqueness constraint will be case sensitive or not. This option defaults to true.

class Person < ActiveRecord::Base
   validates_uniqueness_of :name, :case_sensitive => false
-end
-

The default error message for validates_uniqueness_of is "has already been taken".

+end +

The default error message for validates_uniqueness_of is "has already been taken".

2.11. The `validates_each` helper

This helper validates attributes against a block. It doesn’t have a predefined validation function. You should create one using a block, and every attribute passed to validates_each will be tested against it. In the following example, we don’t want names and surnames to begin with lower case.

class Person < ActiveRecord::Base
+  validates_each :name, :surname do |model, attr, value|
+    model.errors.add(attr, 'Must start with upper case') if value =~ /^[a-z]/
+  end
+end

The block receives the model, the attribute’s name and the attribute’s value. You can do anything you like to check for valid data within the block. If your validation fails, you can add an error message to the model, therefore making it invalid.

4. Common validation options

3. Common Validation Options

There are some common options that all the validation helpers can use. Here they are, except for the :if and :unless options, which we'll cover right at the next topic.

4.1. The `:allow_nil` option

You may use the :allow_nil option everytime you want to trigger a validation only if the value being validated is not nil. You may be asking yourself if it makes any sense to use :allow_nil and validates_presence_of together. Well, it does. Remember, validation will be skipped only for nil attributes, but empty strings are not considered nil.

There are some common options that all the validation helpers can use. Here they are, except for the :if and :unless options, which are discussed later in the conditional validation topic.

3.1. The `:allow_nil` option

The :allow_nil option skips the validation when the value being validated is nil. You may be asking yourself if it makes any sense to use :allow_nil and validates_presence_of together. Well, it does. Remember, the validation will be skipped only for nil attributes, but empty strings are not considered nil.

class Coffee < ActiveRecord::Base
   validates_inclusion_of :size, :in => %w(small medium large),
     :message => "%s is not a valid size", :allow_nil => true
+end

3.2. The `:allow_blank` option

The :allow_blank: option is similar to the +:allow_nil option. This option will let validation pass if the attribute’s value is nil or an empty string, i.e., any value that returns true for blank?.

class Topic < ActiveRecord::Base
+  validates_length_of :title, :is => 5, :allow_blank => true
 end
-

4.2. The `:message` option

As stated before, the :message option lets you specify the message that will be added to the errors collection when validation fails. When this option is not used, Active Record will use the respective default error message for each validation helper.

4.3. The `:on` option

As stated before, the :on option lets you specify when the validation should happen. The default behaviour for all the built-in validation helpers is to be ran on save (both when you're creating a new record and when you're updating it). If you want to change it, you can use :on => :create to run the validation only when a new record is created or :on => :update to run the validation only when a record is updated.

+ +Topic.create("title" => "").valid? # => true +Topic.create("title" => nil).valid? # => true

3.3. The `:message` option

As you’ve already seen, the :message option lets you specify the message that will be added to the errors collection when validation fails. When this option is not used, Active Record will use the respective default error message for each validation helper, together with the attribute name.

3.4. The `:on` option

The :on option lets you specify when the validation should happen. The default behavior for all the built-in validation helpers is to be ran on save (both when you’re creating a new record and when you’re updating it). If you want to change it, you can use :on => :create to run the validation only when a new record is created or :on => :update to run the validation only when a record is updated.

# => it will be possible to create the record with a 'non-numerical age' validates_numericality_of :age, :on => :update - # => the default + # => the default (validates on both create and update) validates_presence_of :name, :on => :save -end -

+end -

5. Conditional validation

4. Conditional validation

Sometimes it will make sense to validate an object just when a given predicate is satisfied. You can do that by using the :if and :unless options, which can take a symbol, a string or a Ruby Proc. You may use the :if option when you want to specify when the validation should happen. If you want to specify when the validation should not happen, then you may use the :unless option.

5.1. Using a symbol with the `:if` and `:unless` options

You can associated the :if and :unless options with a symbol corresponding to the name of a method that will get called right before validation happens. This is the most commonly used option.

4.1. Using a symbol with the `:if` and `:unless` options

You can associate the :if and :unless options with a symbol corresponding to the name of a method that will get called right before validation happens. This is the most commonly used option.

def paid_with_card? payment_type == "card" end -end -

5.2. Using a string with the `:if` and `:unless` options

You can also use a string that will be evaluated using :eval and needs to contain valid Ruby code. You should use this option only when the string represents a really short condition.

+end

4.2. Using a string with the `:if` and `:unless` options

You can also use a string that will be evaluated using :eval and needs to contain valid Ruby code. You should use this option only when the string represents a really short condition.

class Person < ActiveRecord::Base
   validates_presence_of :surname, :if => "name.nil?"
-end
-

5.3. Using a Proc object with the `:if` and :`unless` options

Finally, it's possible to associate :if and :unless with a Ruby Proc object which will be called. Using a Proc object can give you the hability to write a condition that will be executed only when the validation happens and not when your code is loaded by the Ruby interpreter. This option is best suited when writing short validation methods, usually one-liners.

+end +

4.3. Using a Proc object with the `:if` and :`unless` options

Finally, it’s possible to associate :if and :unless with a Ruby Proc object which will be called. Using a Proc object can give you the hability to write a condition that will be executed only when the validation happens and not when your code is loaded by the Ruby interpreter. This option is best suited when writing short validation methods, usually one-liners.

class Account < ActiveRecord::Base
   validates_confirmation_of :password,
     :unless => Proc.new { |a| a.password.blank? }
-end
-

+end -

6. Writing your own validation methods

5. Writing your own validation methods

When the built-in validation helpers are not enough for your needs, you can write your own validation methods, by implementing one or more of the validate, validate_on_create or validate_on_update methods. As the names of the methods states, the right method to implement depends on when you want the validations to be ran. The meaning of valid is still the same: to make an object invalid you just need to add a message to it's errors collection.

class Invoice < ActiveRecord::Base
-  def validate_on_create
-    errors.add(:expiration_date, "can't be in the past") if
-      !expiration_date.blank? and expiration_date < Date.today
-  end
-end
-

If your validation rules are too complicated and you want to break them in small methods, you can implement all of them and call one of validate, validate_on_create or validate_on_update methods, passing it the symbols for the methods' names.

When the built-in validation helpers are not enough for your needs, you can write your own validation methods. You can do that by implementing methods that verify the state of your models and add messages to their errors collection when they are invalid. You must then register those methods by using one or more of the validate, validate_on_create or validate_on_update class methods, passing in the symbols for the validation methods' names. You can pass more than one symbol for each class method and the respective validations will be ran in the same order as they were registered.

errors.add(:discount, "can't be greater than total value") unless discount <= total_value end -end -

+end

You can even create your own validation helpers and reuse them in several different models. Here is an example where we create a custom validation helper to validate the format of fields that represent email addresses:

module ActiveRecord
+  module Validations
+    module ClassMethods
+      def validates_email_format_of(value)
+        validates_format_of value,
+          :with => /\A[\w\._%-]+@[\w\.-]+\.[a-zA-Z]{2,4}\z/,
+          :if => Proc.new { |u| !u.email.blank? },
+          :message => "Invalid format for email address"
+      end
+    end
+  end
+end

The recipe is simple: just create a new validation method inside the ActiveRecord::Validations::ClassMethods module. You can put this code in a file inside your application’s lib folder, and then requiring it from your environment.rb or any other file inside config/initializers. You can use this helper like this:

class Person < ActiveRecord::Base
+  validates_email_format_of :email_address
+end

7. Using the `errors` collection

6. Manipulating the `errors` collection

You can do more than just call valid? upon your objects based on the existance of the errors collection. Here is a list of the other available methods that you can use to manipulate errors or ask for an object's state.

-add_to_base lets you add errors messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of it's attributes. add_to_base receives a string with the message. +add_to_base lets you add errors messages that are related to the object’s state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of it’s attributes. add_to_base receives a string with the message.

def

(

"This person is invalid because ..."

)

end

add lets you manually add messages that are related to particular attributes. When writing those messages, keep in mind that Rails will prepend them with the name of the attribute that holds the error, so write it in a way that makes sense. add receives a symbol with the name of the attribute that you want to add the message to and the message itself. @@ -844,9 +736,8 @@ http://www.gnu.org/software/src-highlite --> def a_method_used_for_validation_purposes errors.add(:name, "can't have the characters !@#$%*()_-+=") end -end -

end

invalid? is used when you want to check if a particular attribute is invalid. It receives a symbol with the name of the attribute that you want to check. @@ -863,9 +754,8 @@ http://www.gnu.org/software/src-highlite --> end person = Person.new(:name => "John Doe") -person.invalid?(:email) # => true -

)

# => true

on is used when you want to check the error messages for a specific attribute. It will return different kinds of objects depending on the state of the errors collection for the given attribute. If there are no errors related to the attribute, on will return nil. If there is just one errors message for this attribute, on will return a string with the message. When errors holds two or more error messages for the attribute, on will return an array of strings, each one with one error message. @@ -894,12 +784,11 @@ person.errors.< person = Person.new person.valid? # => false person.errors.on(:name) -# => ["can't be blank", "is too short (minimum is 3 characters)"] -

# => ["can't be blank", "is too short (minimum is 3 characters)"]

-clear is used when you intentionally want to clear all the messages in the errors collection. However, calling errors.clear upon an invalid object won't make it valid: the errors collection will now be empty, but the next time you call valid? or any method that tries to save this object to the database, the validations will run. If any of them fails, the errors collection will get filled again. +clear is used when you intentionally want to clear all the messages in the errors collection. However, calling errors.clear upon an invalid object won’t make it valid: the errors collection will now be empty, but the next time you call valid? or any method that tries to save this object to the database, the validations will run. If any of them fails, the errors collection will get filled again.

@@ -922,34 +811,131 @@ person.errors.< person.errors.empty? # => true p.save # => false p.errors.on(:name) -# => ["can't be blank", "is too short (minimum is 3 characters)"] - +# => ["can't be blank", "is too short (minimum is 3 characters)"] -

8. Callbacks

7. Using the `errors` collection in your view templates

Callbacks are methods that get called at certain moments of an object's lifecycle. With callbacks it's possible to write code that will run whenever an Active Record object is created, saved, updated, deleted or loaded from the database.

8.1. Callbacks registration

In order to use the available callbacks, you need to registrate them. There are two ways of doing that.

8.2. Registering callbacks by overriding the callback methods

You can specify the callback method directly, by overriding it. Let's see how it works using the before_validation callback, which will surprisingly run right before any validation is done.

Rails provides built-in helpers to display the error messages of your models in your view templates. When creating a form with the form_for helper, you can use the error_messages method on the form builder to render all failed validation messages for the current model instance.

class User < ActiveRecord::Base
-  validates_presence_of :login, :email
-
-  protected
-  def before_validation
-    if self.login.nil?
-      self.login = email unless email.blank?
-    end
+class Product < ActiveRecord::Base
+  validates_presence_of :description, :value
+  validates_numericality_of :value, :allow_nil => true
+end

+ + +<% form_for(@product) do |f| %> + <%= f.error_messages %> + <p> + <%= f.label :description %><br /> + <%= f.text_field :description %> + </p> + <p> + <%= f.label :value %><br /> + <%= f.text_field :value %> + </p> + <p> + <%= f.submit "Create" %> + </p> +<% end %> + + + + + + +You can also use the error_messages_for helper to display the error messages of a model assigned to a view template. It’s very similar to the previous example and will achieve exactly the same result. + + +<%= error_messages_for :product %> + +The displayed text for each error message will always be formed by the capitalized name of the attribute that holds the error, followed by the error message itself. +Both the form.error_messages and the error_messages_for helpers accept options that let you customize the div element that holds the messages, changing the header text, the message below the header text and the tag used for the element that defines the header. + + +<%= f.error_messages :header_message => "Invalid product!", + :message => "You'll need to fix the following fields:", + :header_tag => :h3 %> + +Which results in the following content + + + + + +If you pass nil to any of these options, it will get rid of the respective section of the div. +It’s also possible to change the CSS classes used by the error_messages helper. These classes are automatically defined at the scaffold.css file, generated by the scaffold script. If you’re not using scaffolding, you can still define those CSS classes at your CSS files. Here is a list of the default CSS classes. + + + +.fieldWithErrors - Style for the form fields with errors. + + + + +#errorExplanation - Style for the div element with the error messages. + + + + +#errorExplanation h2 - Style for the header of the div element. + + + + +#errorExplanation p - Style for the paragraph that holds the message that appears right below the header of the div element. + + + + +#errorExplanation ul li - Style for the list of error messages. + + + +7.1. Changing the way form fields with errors are displayed +By default, form fields with errors are displayed enclosed by a div element with the fieldWithErrors CSS class. However, we can write some Ruby code to override the way Rails treats those fields by default. Here is a simple example where we change the Rails behaviour to always display the error messages in front of each of the form fields with errors. The error messages will be enclosed by a span element with a validation-error CSS class. There will be no div element enclosing the input element, so we get rid of that red border around the text field. You can use the validation-error CSS class to style it anyway you want. + + +ActionView::Base.field_error_proc = Proc.new do |html_tag, instance| + if instance.error_message.kind_of?(Array) + %(#{html_tag}<span class='validation-error'>  + #{instance.error_message.join(',')}</span>) + else + %(#{html_tag}<span class='validation-error'>  + #{instance.error_message}</span>) end -end - -8.3. Registering callbacks by using macro-style class methods -The other way you can register a callback method is by implementing it as an ordinary method, and then using a macro-style class method to register it as a callback. The last example could be written like that: +end

This will result in something like the following content:

The way form fields with errors are treated is defined by the ActionView::Base.field_error_proc Ruby Proc. This Proc receives two parameters:

+
+A string with the HTML tag +
+
+
+An object of the ActionView::Helpers::InstanceTag class. +
+

+ +

8. Callbacks

Callbacks are methods that get called at certain moments of an object’s lifecycle. With callbacks it’s possible to write code that will run whenever an Active Record object is created, saved, updated, deleted or loaded from the database.

8.1. Callbacks registration

In order to use the available callbacks, you need to registrate them. You can do that by implementing them as an ordinary methods, and then using a macro-style class method to register then as callbacks.

self.login = email unless email.blank? end end -end -

The macro-style class methods can also receive a block. Rails best practices say that you should only use this style of registration if the code inside your block is so short that it fits in just one line.

+end

validates_presence_of :login, :email before_create {|user| user.name = user.login.capitalize if user.name.blank?} -end -

In Rails, the preferred way of registering callbacks is by using macro-style class methods. The main advantages of using macro-style class methods are:

-
-You can add more than one method for each type of callback. Those methods will be queued for execution at the same order they were registered. -
-
-
-Readability, since your callback declarations will live at the beggining of your models' files. -
-

+end

@@ -1002,11 +973,57 @@ Readability, since your callback declarations will live at the beggining of your

9. Available callbacks

9. Conditional callbacks

Here is a list with all the available Active Record callbacks, listed in the same order in which they will get called during the respective operations.

9.1. Callbacks called both when creating or updating a record.

Like in validations, we can also make our callbacks conditional, calling then only when a given predicate is satisfied. You can do that by using the :if and :unless options, which can take a symbol, a string or a Ruby Proc. You may use the :if option when you want to specify when the callback should get called. If you want to specify when the callback should not be called, then you may use the :unless option.

9.1. Using a symbol with the `:if` and `:unless` options

You can associate the :if and :unless options with a symbol corresponding to the name of a method that will get called right before the callback. If this method returns false the callback won’t be executed. This is the most common option. Using this form of registration it’s also possible to register several different methods that should be called to check the if the callback should be executed.

class Order < ActiveRecord::Base
+  before_save :normalize_card_number, :if => :paid_with_card?
+end

9.2. Using a string with the `:if` and `:unless` options

You can also use a string that will be evaluated using :eval and needs to contain valid Ruby code. You should use this option only when the string represents a really short condition.

class Order < ActiveRecord::Base
+  before_save :normalize_card_number, :if => "paid_with_card?"
+end

9.3. Using a Proc object with the `:if` and :`unless` options

Finally, it’s possible to associate :if and :unless with a Ruby Proc object. This option is best suited when writing short validation methods, usually one-liners.

class Order < ActiveRecord::Base
+  before_save :normalize_card_number,
+    :if => Proc.new { |order| order.paid_with_card? }
+end

9.4. Multiple Conditions for Callbacks

When writing conditional callbacks, it’s possible to mix both :if and :unless in the same callback declaration.

class Comment < ActiveRecord::Base
+  after_create :send_email_to_author, :if => :author_wants_emails?,
+    :unless => Proc.new { |comment| comment.post.ignore_comments? }
+end

10. Available callbacks

Here is a list with all the available Active Record callbacks, listed in the same order in which they will get called during the respective operations.

10.1. Callbacks called both when creating or updating a record.

before_validation @@ -1033,8 +1050,8 @@ Readability, since your callback declarations will live at the beggining of your

9.2. Callbacks called only when creating a new record.

10.2. Callbacks called only when creating a new record.

before_validation_on_create @@ -1061,8 +1078,8 @@ Readability, since your callback declarations will live at the beggining of your

9.3. Callbacks called only when updating an existing record.

10.3. Callbacks called only when updating an existing record.

before_validation_on_update @@ -1089,8 +1106,8 @@ Readability, since your callback declarations will live at the beggining of your

9.4. Callbacks called when removing a record from the database.

10.4. Callbacks called when removing a record from the database.

before_destroy @@ -1107,20 +1124,20 @@ Readability, since your callback declarations will live at the beggining of your

The before_destroy and after_destroy callbacks will only be called if you delete the model using either the destroy instance method or one of the destroy or destroy_all class methods of your Active Record class. If you use delete or delete_all no callback operations will run, since Active Record will not instantiate any objects, accessing the records to be deleted directly in the database.

9.5. The `after_initialize` and `after_find` callbacks

The after_initialize callback will be called whenever an Active Record object is instantiated, either by direcly using new or when a record is loaded from the database. It can be useful to avoid the need to directly override your Active Record initialize method.

The after_find callback will be called whenever Active Record loads a record from the database. When used together with after_initialize it will run first, since Active Record will first read the record from the database and them create the model object that will hold it.

The after_initialize and after_find callbacks are a bit different from the others, since the only way to register those callbacks is by defining them as methods. If you try to register after_initialize or after_find using macro-style class methods, they will just be ignored. This behaviour is due to performance reasons, since after_initialize and after_find will both be called for each record found in the database, significantly slowing down the queries.

10.5. The `after_initialize` and `after_find` callbacks

10. Halting Execution

11. Halting Execution

As you start registering new callbacks for your models, they will be queued for execution. This queue will include all your model's validations, the registered callbacks and the database operation to be executed. However, if at any moment one of the before_create, before_save, before_update or before_destroy callback methods returns a boolean false (not nil) value, this execution chain will be halted and the desired operation will not complete: your model will not get persisted in the database, or your records will not get deleted and so on.

As you start registering new callbacks for your models, they will be queued for execution. This queue will include all your model’s validations, the registered callbacks and the database operation to be executed. However, if at any moment one of the before_create, before_save, before_update or before_destroy callback methods returns a boolean false (not nil) value or raise and exception, this execution chain will be halted and the desired operation will not complete: your model will not get persisted in the database, or your records will not get deleted and so on. It’s because the whole callback chain is wrapped in a transaction, so raising an exception or returning false fires a database ROLLBACK.

11. Callback classes

12. Callback classes

Sometimes the callback methods that you'll write will be useful enough to be reused at other models. Active Record makes it possible to create classes that encapsulate the callback methods, so it becomes very easy to reuse them.

Here's an example where we create a class with a after_destroy callback for a PictureFile model.

Sometimes the callback methods that you’ll write will be useful enough to be reused at other models. Active Record makes it possible to create classes that encapsulate the callback methods, so it becomes very easy to reuse them.

Here’s an example where we create a class with a after_destroy callback for a PictureFile model.

def after_destroy(picture_file) File.delete(picture_file.filepath) if File.exists?(picture_file.filepath) end -end -

When declared inside a class the callback method will receive the model object as a parameter. We can now use it this way:

+end

When declared inside a class the callback method will receive the model object as a parameter. We can now use it this way:

class PictureFile < ActiveRecord::Base
   after_destroy PictureFileCallbacks.new
-end
-

Note that we needed to instantiate a new PictureFileCallbacks object, since we declared our callback as an instance method. Sometimes it will make more sense to have it as a class method.

end

Note that we needed to instantiate a new PictureFileCallbacks object, since we declared our callback as an instance method. Sometimes it will make more sense to have it as a class method.

def self.after_destroy(picture_file) File.delete(picture_file.filepath) if File.exists?(picture_file.filepath) end -end -

If the callback method is declared this way, it won't be necessary to instantiate a PictureFileCallbacks object.

+end

If the callback method is declared this way, it won’t be necessary to instantiate a PictureFileCallbacks object.

class PictureFile < ActiveRecord::Base
   after_destroy PictureFileCallbacks
-end
-

You can declare as many callbacks as you want inside your callback classes.

+end +

You can declare as many callbacks as you want inside your callback classes.

12. Observers

13. Observers

Active Record callbacks are a powerful feature, but they can pollute your model implementation with code that's not directly related to the model's purpose. In object-oriented software, it's always a good idea to design your classes with a single responsability in the whole system. For example, it wouldn't make much sense to have a User model with a method that writes data about a login attempt to a log file. Whenever you're using callbacks to write code that's not directly related to your model class purposes, it may be a good moment to create an Observer.

An Active Record Observer is an object that links itself to a model and register it's methods for callbacks. Your model's implementation remain clean, while you can reuse the code in the Observer to add behaviuor to more than one model class. Ok, you may say that we can also do that using callback classes, but it would still force us to add code to our model's implementation.

Observer classes are subclasses of the ActiveRecord::Observer class. When this class is subclassed, Active Record will look at the name of the new class and then strip the Observer part to find the name of the Active Record class to observe.

Consider a Registration model, where we want to send an email everytime a new registration is created. Since sending emails is not directly related to our model's purpose, we could create an Observer to do just that:

Active Record callbacks are a powerful feature, but they can pollute your model implementation with code that’s not directly related to the model’s purpose. In object-oriented software, it’s always a good idea to design your classes with a single responsibility in the whole system. For example, it wouldn’t make much sense to have a User model with a method that writes data about a login attempt to a log file. Whenever you’re using callbacks to write code that’s not directly related to your model class purposes, it may be a good moment to create an Observer.

An Active Record Observer is an object that links itself to a model and registers its methods for callbacks. Your model’s implementation remains clean, while you can reuse the code in the Observer to add behaviour to more than one model class. OK, you may say that we can also do that using callback classes, but it would still force us to add code to our model’s implementation.

Observer classes are subclasses of the ActiveRecord::Observer class. When this class is subclassed, Active Record will look at the name of the new class and then strip the Observer part to find the name of the Active Record class to observe.

Consider a Registration model, where we want to send an email every time a new registration is created. Since sending emails is not directly related to our model’s purpose, we could create an Observer to do just that:

def after_create(model) # code to send registration confirmation emails... end -end -

Like in callback classes, the observer's methods receive the observed model as a parameter.

Sometimes using the ModelName + Observer naming convention won't be the best choice, mainly when you want to use the same observer for more than one model class. It's possible to explicity specify the models that our observer should observe.

+end

Like in callback classes, the observer’s methods receive the observed model as a parameter.

Sometimes using the ModelName + Observer naming convention won’t be the best choice, mainly when you want to use the same observer for more than one model class. It’s possible to explicity specify the models that our observer should observe.

class Auditor < ActiveRecord::Observer
   observe User, Registration, Invoice
-end
-

12.1. Registering observers

If you payed attention, you may be wondering where Active Record Observers are referenced in our applications, so they get instantiate and begin to interact with our models. For observers to work we need to register them somewhere. The usual place to do that is in our application's config/environment.rb file. In this file there is a commented out line where we can define the observers that our application should load at start-up.

+end +

13.1. Registering observers

If you paid attention, you may be wondering where Active Record Observers are referenced in our applications, so they get instantiated and begin to interact with our models. For observers to work we need to register them somewhere. The usual place to do that is in our application’s config/environment.rb file. In this file there is a commented-out line where we can define the observers that our application should load at start-up.

# Activate observers that should always be running
-config.active_record.observers = :registration_observer, :auditor
-

You can uncomment the line with config.active_record.observers and change the symbols for the name of the observers that should be registered.

It's also possible to register callbacks in any of the files living at config/environments/, if you want an observer to work only in a specific environment. There is not a config.active_record.observers line at any of those files, but you can simply add it.

12.2. Where to put the observers' source files

By convention, you should always save your observers' source files inside app/models.

+config.active_record.observers = :registration_observer, :auditor +

You can uncomment the line with config.active_record.observers and change the symbols for the name of the observers that should be registered.

It’s also possible to register callbacks in any of the files living at config/environments/, if you want an observer to work only in a specific environment. There is not a config.active_record.observers line at any of those files, but you can simply add it.

13.2. Where to put the observers' source files

By convention, you should always save your observers' source files inside app/models.

13. Changelog

14. Changelog

http://rails.lighthouseapp.com/projects/16213/tickets/26-active-record-validations-and-callbacks

Lighthouse ticket

January 9, 2009: Initial version by Cássio Marques

- - + + diff --git a/railties/doc/guides/html/association_basics.html b/railties/doc/guides/html/association_basics.html index a2f89e3c43..bfe8f3f341 100644 --- a/railties/doc/guides/html/association_basics.html +++ b/railties/doc/guides/html/association_basics.html @@ -1,276 +1,108 @@ - - A Guide to Active Record Associations - - - - - + + A Guide to Active Record Associations + + + + - -

- - - -

A Guide to Active Record Associations

+ + + +

A Guide to Active Record Associations

This guide covers the association features of Active Record. By referring to this guide, you will be able to:

Declare associations between Active Record models @@ -291,7 +123,7 @@ Use the methods added to your models by creating associations

1. Why Associations?

Why do we need associations between models? Because they make common operations simpler and easier in your code. For example, consider a simple Rails application that includes a model for customers and a model for orders. Each customer can have many orders. Without associations, the model declarations would look like this:

end class Order < ActiveRecord::Base -end -

Now, suppose we wanted to add a new order for an existing customer. We'd need to do something like this:

+end

Now, suppose we wanted to add a new order for an existing customer. We’d need to do something like this:

@order = Order.create(:order_date => Time.now, :customer_id => @customer.id)
-

Or consider deleting a customer, and ensuring that all of its orders get deleted as well:

@order = Order.create(:order_date => Time.now, :customer_id => @customer.id)

Or consider deleting a customer, and ensuring that all of its orders get deleted as well:

@orders.each do |order| order.destroy end -@customer.destroy -

With Active Record associations, we can streamline these - and other - operations by declaratively telling Rails that there is a connection between the two models. Here's the revised code for setting up customers and orders:

+@customer.destroy

With Active Record associations, we can streamline these - and other - operations by declaratively telling Rails that there is a connection between the two models. Here’s the revised code for setting up customers and orders:

class Order < ActiveRecord::Base belongs_to :customer -end -

With this change, creating a new order for a particular customer is easier:

+end

With this change, creating a new order for a particular customer is easier:

@order = @customer.orders.create(:order_date => Time.now)
-

Deleting a customer and all of its orders is much easier:

@order = @customer.orders.create(:order_date => Time.now)

Deleting a customer and all of its orders is much easier:

@customer.destroy
-

To learn more about the different types of associations, read the next section of this Guide. That's followed by some tips and tricks for working with associations, and then by a complete reference to the methods and options for associations in Rails.

@customer.destroy

To learn more about the different types of associations, read the next section of this Guide. That’s followed by some tips and tricks for working with associations, and then by a complete reference to the methods and options for associations in Rails.

2. The Types of Associations

In Rails, an association is a connection between two Active Record models. Associations are implemented using macro-style calls, so that you can declaratively add features to your models. For example, by declaring that one model belongs_to another, you instruct Rails to maintain Primary Key-Foreign Key information between instances of the two models, and you also get a number of utility methods added to your model. Rails supports six types of association:

belongs_to @@ -390,9 +216,9 @@ http://www.gnu.org/software/src-highlite -->

In the remainder of this guide, you'll learn how to declare and use the various forms of associations. But first, a quick introduction to the situations where each association type is appropriate.

In the remainder of this guide, you’ll learn how to declare and use the various forms of associations. But first, a quick introduction to the situations where each association type is appropriate.

2.1. The `belongs_to` Association

A belongs_to association sets up a one-to-one connection with another model, such that each instance of the declaring model "belongs to" one instance of the other model. For example, if your application includes customers and orders, and each order can be assigned to exactly one customer, you'd declare the order model this way:

class Order < ActiveRecord::Base
   belongs_to :customer
-end
-

+end

belongs_to Association Diagram

2.2. The `has_one` Association

A has_one association also sets up a one-to-one connection with another model, but with somewhat different semantics (and consequences). This association indicates that each instance of a model contains or possesses one instance of another model. For example, if each supplier in your application has only one account, you'd declare the supplier model like this:

class Supplier < ActiveRecord::Base
   has_one :account
-end
-

+end

has_one Association Diagram

2.3. The `has_many` Association

A has_many association indicates a one-to-many connection with another model. You'll often find this association on the "other side" of a belongs_to association. This association indicates that each instance of the model has zero or more instances of another model. For example, in an application containing customers and orders, the customer model could be declared like this:

A has_many association indicates a one-to-many connection with another model. You’ll often find this association on the "other side" of a belongs_to association. This association indicates that each instance of the model has zero or more instances of another model. For example, in an application containing customers and orders, the customer model could be declared like this:

class Customer < ActiveRecord::Base
   has_many :orders
-end
-

+end

@@ -438,11 +261,11 @@ http://www.gnu.org/software/src-highlite --> The name of the other model is pluralized when declaring a has_many association.

has_many Association Diagram

2.4. The `has_many :through` Association

A has_many :through association is often used to set up a many-to-many connection with another model. This association indicates that the declaring model can be matched with zero or more instances of another model by proceeding through a third model. For example, consider a medical practice where patients make appointments to see physicians. The relevant association declarations could look like this:

class Patient < ActiveRecord::Base has_many :appointments has_many :physicians, :through => :appointments -end -

+end

has_many :through Association Diagram

The has_many :through association is also useful for setting up "shortcuts" through nested :has_many associations. For example, if a document has many sections, and a section has many paragraphs, you may sometimes want to get a simple collection of all paragraphs in the document. You could set that up this way:

class Paragraph < ActiveRecord::Base belongs_to :section -end -

+end

2.5. The `has_one :through` Association

A has_one :through association sets up a one-to-one connection with another model. This association indicates that the declaring model can be matched with one instance of another model by proceeding through a third model. For example, if each supplier has one account, and each account is associated with one account history, then the customer model could look like this:

class AccountHistory < ActiveRecord::Base belongs_to :account -end -

+end

has_one :through Association Diagram

2.6. The `has_and_belongs_to_many` Association

A has_and_belongs_to_many association creates a direct many-to-many connection with another model, with no intervening model. For example, if your application includes assemblies and parts, with each assembly having many parts and each part appearing in many assemblies, you could declare the models this way:

class Part < ActiveRecord::Base has_and_belongs_to_many :assemblies -end -

+end

has_and_belongs_to_many Association Diagram

2.7. Choosing Between `belongs_to` and `has_one`

If you want to set up a 1-1 relationship between two models, you'll need to add belongs_to to one, and has_one to the other. How do you know which is which?

The distinction is in where you place the foreign key (it goes on the table for the class declaring the belongs_to association), but you should give some thought to the actual meaning of the data as well. The has_one relationship says that one of something is yours - that is, that something points back to you. For example, it makes more sense to say that a supplier owns an account than that an account owns a supplier. This suggests that the correct relationships are like this:

If you want to set up a 1-1 relationship between two models, you’ll need to add belongs_to to one, and has_one to the other. How do you know which is which?

class Account < ActiveRecord::Base belongs_to :supplier -end -

The corresponding migration might look like this:

+end +

The corresponding migration might look like this:

drop_table :accounts drop_table :suppliers end -end -

+end

@@ -579,7 +396,7 @@ http://www.gnu.org/software/src-highlite -->

2.8. Choosing Between `has_many :through` and `has_and_belongs_to_many`

Rails offers two different ways to declare a many-to-many relationship between models. The simpler way is to use has_and_belongs_to_many, which allows you to make the association directly:

class Part < ActiveRecord::Base has_and_belongs_to_many :assemblies -end -

The second way to declare a many-to-many relationship is to use has_many :through. This makes the association indirectly, through a join model:

+end +

The second way to declare a many-to-many relationship is to use has_many :through. This makes the association indirectly, through a join model:

class Part < ActiveRecord::Base has_many :manifests has_many :assemblies, :through => :manifests -end -

The simplest rule of thumb is that you should set up a has_many :through relationship if you need to work with the relationship model as an independent entity. If you don't need to do anything with the relationship model, it may be simpler to set up a has_and_belongs_to_many relationship (though you'll need to remember to create the joining table).

You should use has_many :through if you need validations, callbacks, or extra attributes on the join model.

+end +

The simplest rule of thumb is that you should set up a has_many :through relationship if you need to work with the relationship model as an independent entity. If you don’t need to do anything with the relationship model, it may be simpler to set up a has_and_belongs_to_many relationship (though you’ll need to remember to create the joining table).

You should use has_many :through if you need validations, callbacks, or extra attributes on the join model.

2.9. Polymorphic Associations

A slightly more advanced twist on associations is the polymorphic association. With polymorphic associations, a model can belong to more than one other model, on a single association. For example, you might have a picture model that belongs to either an employee model or a product model. Here's how this could be declared:

class Product < ActiveRecord::Base has_many :pictures, :as => :imageable -end -

You can think of a polymorphic belongs_to declaration as setting up an interface that any other model can use. From an instance of the Employee model, you can retrieve a collection of pictures: @employee.pictures. Similarly, you can retrieve @product.pictures. If you have an instance of the Picture model, you can get to its parent via @picture.imageable. To make this work, you need to declare both a foreign key column and a type column in the model that declares the polymorphic interface:

+end +

def self.down drop_table :pictures end -end -

This migration can be simplified by using the t.references form:

+end +

This migration can be simplified by using the t.references form:

def self.down drop_table :pictures end -end -

+end

Polymorphic Association Diagram

2.10. Self Joins

In designing a data model, you will sometimes find a model that should have a relation to itself. For example, you may want to store all employees in a single database model, but be able to trace relationships such as manager and subordinates. This situation can be modeled with self-joining associations:

class Employee < ActiveRecord::Base
   has_many :subordinates, :class_name => "Employee", :foreign_key => "manager_id"
   belongs_to :manager, :class_name => "Employee"
-end
-

With this setup, you can retrieve @employee.subordinates and @employee.manager.

+end +

With this setup, you can retrieve @employee.subordinates and @employee.manager.

3. Tips, Tricks, and Warnings

Here are a few things you should know to make efficient use of Active Record associations in your Rails applications:

Controlling caching @@ -719,7 +530,7 @@ Controlling association scope

3.1. Controlling Caching

All of the association methods are built around caching that keeps the result of the most recent query available for further operations. The cache is even shared across methods. For example:

customer.orders                 # retrieves orders from the database
 customer.orders.size            # uses the cached copy of orders
-customer.orders.empty?          # uses the cached copy of orders
-

But what if you want to reload the cache, because data might have been changed by some other part of the application? Just pass true to the association call:

# uses the cached copy of orders

But what if you want to reload the cache, because data might have been changed by some other part of the application? Just pass true to the association call:

customer.orders                 # retrieves orders from the database
 customer.orders.size            # uses the cached copy of orders
-customer.orders(true).empty?    # discards the cached copy of orders and goes back to the database
-

+customer.orders(true).empty? # discards the cached copy of orders and goes back to the database

3.2. Avoiding Name Collisions

You are not free to use just any name for your associations. Because creating an association adds a method with that name to the model, it is a bad idea to give an association a name that is already used for an instance method of ActiveRecord::Base. The association method would override the base method and break things. For instance, attributes or connection are bad names for associations.

3.3. Updating the Schema

Associations are extremely useful, but they are not magic. You are responsible for maintaining your database schema to match your associations. In practice, this means two things, depending on what sort of associations you are creating. For belongs_to associations you need to create foreign keys, and for has_and_belongs_to_many associations you need to create the appropriate join table.

3.3.1. Creating Foreign Keys for `belongs_to` Associations

When you declare a belongs_to association, you need to create foreign keys as appropriate. For example, consider this model:

class Order < ActiveRecord::Base
   belongs_to :customer
-end
-

This declaration needs to be backed up by the proper foreign key declaration on the orders table:

+end +

This declaration needs to be backed up by the proper foreign key declaration on the orders table:

def self.down drop_table :orders end -end -

If you create an association some time after you build the underlying model, you need to remember to create an add_column migration to provide the necessary foreign key.

+end +

If you create an association some time after you build the underlying model, you need to remember to create an add_column migration to provide the necessary foreign key.

3.3.2. Creating Join Tables for `has_and_belongs_to_many` Associations

If you create a has_and_belongs_to_many association, you need to explicitly create the joining table. Unless the name of the join table is explicitly specified by using the :join_table option, Active Record create the name by using the lexical order of the class names. So a join between customer and order models will give the default join table name of "customers_orders" because "c" outranks "o" in lexical ordering.

@@ -785,7 +592,7 @@ http://www.gnu.org/software/src-highlite --> The precedence between model names is calculated using the < operator for String. This means that if the strings are of different lengths, and the strings are equal when compared up to the shortest length, then the longer string is considered of higher lexical precedence than the shorter one. For example, one would expect the tables "paper_boxes" and "papers" to generate a join table name of "papers_paper_boxes" because of the length of the name "paper_boxes", but it in fact generates a join table name of "paper_boxes_papers".

Whatever the name, you must manually generate the join table with an appropriate migration. For example, consider these associations:

class Part < ActiveRecord::Base has_and_belongs_to_many :assemblies -end -

These need to be backed up by a migration to create the assemblies_parts table. This table should be created without a primary key:

+end +

These need to be backed up by a migration to create the assemblies_parts table. This table should be created without a primary key:

def self.down drop_table :assemblies_parts end -end -

+end

3.4. Controlling Association Scope

By default, associations look for objects only within the current module's scope. This can be important when you declare Active Record models within a module. For example:

By default, associations look for objects only within the current module’s scope. This can be important when you declare Active Record models within a module. For example:

belongs_to :supplier end end -end -

This will work fine, because both the Supplier and the Account class are defined within the same scope. But this will not work, because Supplier and Account are defined in different scopes:

+end +

This will work fine, because both the Supplier and the Account class are defined within the same scope. But this will not work, because Supplier and Account are defined in different scopes:

belongs_to :supplier end end -end -

To associate a model with a model in a different scope, you must specify the complete class name in your association declaration:

+end +

To associate a model with a model in a different scope, you must specify the complete class name in your association declaration:

belongs_to :supplier, :class_name => "MyApplication::Business::Supplier" end end -end -

+end

4. Detailed Association Reference

The following sections give the details of each type of association, including the methods that they add and the options that you can use when declaring an association.

4.1. The `belongs_to` Association

The belongs_to association creates a one-to-one match with another model. In database terms, this association says that this class contains the foreign key. If the other class contains the foreign key, then you should use has_one instead.

4.1.1. Methods Added by `belongs_to`

When you declare a belongs_to assocation, the declaring class automatically gains five methods related to the association:

association(force_reload = false) @@ -912,7 +714,7 @@ http://www.gnu.org/software/src-highlite -->

In all of these methods, association is replaced with the symbol passed as the first argument to belongs_to. For example, given the declaration:

class Order < ActiveRecord::Base
   belongs_to :customer
-end
-

Each instance of the order model will have these methods:

end

Each instance of the order model will have these methods:

customer= customer.nil? build_customer -create_customer -

+create_customer

`association(force_reload = false)`

The association method returns the associated object, if any. If no associated object is found, it returns nil.

@customer = @order.customer
-

If the associated object has already been retrieved from the database for this object, the cached version will be returned. To override this behavior (and force a database read), pass true as the force_reload argument.

@customer = @order.customer

`association=(associate)`

The association= method assigns an associated object to this object. Behind the scenes, this means extracting the primary key from the associate object and setting this object's foreign key to the same value.

@order.customer = @customer
-

@order.customer = @customer

`association.nil?`

The association.nil? method returns true if there is no associated object.

if @order.customer.nil?
   @msg = "No customer found for this order"
-end
-

+end

`build_association(attributes = {})`

The build_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object's foreign key will be set, but the associated object will _not_ yet be saved.

The build_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object’s foreign key will be set, but the associated object will not yet be saved.

@customer = @order.build_customer({:customer_number => 123, :customer_name => "John Doe"})
-

@customer = @order.build_customer({:customer_number => 123, :customer_name => "John Doe"})

`create_association(attributes = {})`

The create_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object's foreign key will be set. In addition, the associated object _will_ be saved (assuming that it passes any validations).

The create_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object’s foreign key will be set. In addition, the associated object will be saved (assuming that it passes any validations).

@customer = @order.create_customer({:customer_number => 123, :customer_name => "John Doe"})
-

@customer = @order.create_customer({:customer_number => 123, :customer_name => "John Doe"})

4.1.2. Options for `belongs_to`

In many situations, you can use the default behavior of belongs_to without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a belongs_to association. For example, an association with several options might look like this:

class Order < ActiveRecord::Base
   belongs_to :customer, :counter_cache => true, :conditions => "active = 1"
-end
-

The belongs_to association supports these options:

end

The belongs_to association supports these options:

:class_name @@ -1047,7 +841,7 @@ http://www.gnu.org/software/src-highlite -->

`:class_name`

If the name of the other model cannot be derived from the association name, you can use the :class_name option to supply the model name. For example, if an order belongs to a customer, but the actual name of the model containing customers is Patron, you'd set things up this way:

class Order < ActiveRecord::Base
   belongs_to :customer, :class_name => "Patron"
-end
-

+end

`:conditions`

The :conditions option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL WHERE clause).

class Order < ActiveRecord::Base
   belongs_to :customer, :conditions => "active = 1"
-end
-

+end

`:counter_cache`

The :counter_cache option can be used to make finding the number of belonging objects more efficient. Consider these models:

end class Customer < ActiveRecord::Base has_many :orders -end -

With these declarations, asking for the value of @customer.orders.size requires making a call to the database to perform a COUNT(*) query. To avoid this call, you can add a counter cache to the belonging model:

+end +

end class Customer < ActiveRecord::Base has_many :orders -end -

With this declaration, Rails will keep the cache value up to date, and then return that value in response to the .size method.

Although the :counter_cache option is specified on the model that includes the belongs_to declaration, the actual column must be added to the associated model. In the case above, you would need to add a column named orders_count to the Customer model. You can override the default column name if you need to:

+end +

With this declaration, Rails will keep the cache value up to date, and then return that value in response to the .size method.

end class Customer < ActiveRecord::Base has_many :orders -end -

Counter cache columns are added to the containing model's list of read-only attributes through attr_readonly.

+end +

Counter cache columns are added to the containing model’s list of read-only attributes through attr_readonly.

`:dependent`

@@ -1121,7 +910,7 @@ http://www.gnu.org/software/src-highlite -->

`:foreign_key`

By convention, Rails guesses that the column used to hold the foreign key on this model is the name of the association with the suffix _id added. The :foreign_key option lets you set the name of the foreign key directly:

class Order < ActiveRecord::Base
   belongs_to :customer, :class_name => "Patron", :foreign_key => "patron_id"
-end
-

+end

@@ -1140,7 +928,7 @@ http://www.gnu.org/software/src-highlite -->

`:include`

You can use the :include option to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models:

end class Customer < ActiveRecord::Base has_many :orders -end -

If you frequently retrieve customers directly from line items (@line_item.order.customer), then you can make your code somewhat more efficient by including customers in the association from line items to orders:

+end +

end class Customer < ActiveRecord::Base has_many :orders -end -

+end

- +

There's no need to use :include for immediate associations - that is, if you have Order belongs_to :customer, then the customer is eager-loaded automatically when it's needed. There’s no need to use :include for immediate associations - that is, if you have Order belongs_to :customer, then the customer is eager-loaded automatically when it’s needed.

`:polymorphic`

Passing true to the :polymorphic option indicates that this is a polymorphic association. Polymorphic associations were discussed in detail earlier in this guide.

`:readonly`

If you set the :readonly option to true, then the associated object will be read-only when retrieved via the association.

`:select`

The :select option lets you override the SQL SELECT clause that is used to retrieve data about the associated object. By default, Rails retrieves all columns.

@@ -1197,14 +983,14 @@ http://www.gnu.org/software/src-highlite -->

`:validate`

If you set the :validate option to true, then associated objects will be validated whenever you save this object. By default, this is false: associated objects will not be validated when this object is saved.

4.1.3. When are Objects Saved?

Assigning an object to a belongs_to association does not automatically save the object. It does not save the associated object either.

4.2. The has_one Association

The has_one association creates a one-to-one match with another model. In database terms, this association says that the other class contains the foreign key. If this class contains the foreign key, then you should use belongs_to instead.

4.2.1. Methods Added by `has_one`

When you declare a has_one association, the declaring class automatically gains five methods related to the association:

association(force_reload = false) @@ -1231,7 +1017,7 @@ http://www.gnu.org/software/src-highlite -->

In all of these methods, association is replaced with the symbol passed as the first argument to has_one. For example, given the declaration:

class Supplier < ActiveRecord::Base
   has_one :account
-end
-

Each instance of the Supplier model will have these methods:

end

Each instance of the Supplier model will have these methods:

account= account.nil? build_account -create_account -

+create_account

`association(force_reload = false)`

The association method returns the associated object, if any. If no associated object is found, it returns nil.

@account = @supplier.account
-

@account = @supplier.account

`association=(associate)`

The association= method assigns an associated object to this object. Behind the scenes, this means extracting the primary key from this object and setting the associate object's foreign key to the same value.

@suppler.account = @account
-

@suppler.account = @account

`association.nil?`

The association.nil? method returns true if there is no associated object.

if @supplier.account.nil?
   @msg = "No account found for this supplier"
-end
-

+end

`build_association(attributes = {})`

The build_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through its foreign key will be set, but the associated object will _not_ yet be saved.

@account = @supplier.build_account({:terms => "Net 30"})
-

@account = @supplier.build_account({:terms => "Net 30"})

`create_association(attributes = {})`

The create_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through its foreign key will be set. In addition, the associated object _will_ be saved (assuming that it passes any validations).

The create_association method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through its foreign key will be set. In addition, the associated object will be saved (assuming that it passes any validations).

@account = @supplier.create_account({:terms => "Net 30"})
-

@account = @supplier.create_account({:terms => "Net 30"})

4.2.2. Options for `has_one`

In many situations, you can use the default behavior of has_one without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a has_one association. For example, an association with several options might look like this:

class Supplier < ActiveRecord::Base
   has_one :account, :class_name => "Billing", :dependent => :nullify
-end
-

The has_one association supports these options:

end

The has_one association supports these options:

:as @@ -1386,9 +1164,9 @@ http://www.gnu.org/software/src-highlite -->

`:as`

Setting the :as option indicates that this is a polymorphic association. Polymorphic associations are discussed in detail later in this guide.

`:class_name`

If the name of the other model cannot be derived from the association name, you can use the :class_name option to supply the model name. For example, if a supplier has an account, but the actual name of the model containing accounts is Billing, you'd set things up this way:

class Supplier < ActiveRecord::Base
   has_one :account, :class_name => "Billing"
-end
-

+end

`:conditions`

The :conditions option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL WHERE clause).

class Supplier < ActiveRecord::Base
   has_one :account, :conditions => "confirmed = 1"
-end
-

+end

`:dependent`

If you set the :dependent option to :destroy, then deleting this object will call the destroy method on the associated object to delete that object. If you set the :dependent option to :delete, then deleting this object will delete the associated object without calling its destroy method. If you set the :dependent option to :nullify, then deleting this object will set the foreign key in the association object to NULL.

`:foreign_key`

By convention, Rails guesses that the column used to hold the foreign key on the other model is the name of this model with the suffix _id added. The :foreign_key option lets you set the name of the foreign key directly:

class Supplier < ActiveRecord::Base
   has_one :account, :foreign_key => "supp_id"
-end
-

+end

@@ -1431,7 +1206,7 @@ http://www.gnu.org/software/src-highlite -->

`:include`

You can use the :include option to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models:

end class Representative < ActiveRecord::Base has_many :accounts -end -

If you frequently retrieve representatives directly from suppliers (@supplier.account.representative), then you can make your code somewhat more efficient by including representatives in the association from suppliers to accounts:

+end +

end class Representative < ActiveRecord::Base has_many :accounts -end -

+end

`:order`

The :order option dictates the order in which associated objects will be received (in the syntax used by a SQL ORDER BY clause). Because a has_one association will only retrieve a single associated object, this option should not be needed.

`:primary_key`

By convention, Rails guesses that the column used to hold the primary key of this model is id. You can override this and explicitly specify the primary key with the :primary_key option.

`:readonly`

If you set the :readonly option to true, then the associated object will be read-only when retrieved via the association.

`:select`

The :select option lets you override the SQL SELECT clause that is used to retrieve data about the associated object. By default, Rails retrieves all columns.

`:source`

The :source option specifies the source association name for a has_one :through association.

`:source_type`

The :source_type option specifies the source association type for a has_one :through association that proceeds through a polymorphic association.

`:through`

The :through option specifies a join model through which to perform the query. has_one :through associations are discussed in detail later in this guide.

`:validate`

4.2.3. When are Objects Saved?

When you assign an object to a has_one association, that object is automatically saved (in order to update its foreign key). In addition, any object being replaced is also automatically saved, because its foreign key will change too.

If either of these saves fails due to validation errors, then the assignment statement returns false and the assignment itself is cancelled.

If the parent object (the one declaring the has_one association) is unsaved (that is, new_record? returns true) then the child objects are not saved.

If you want to assign an object to a has_one association without saving the object, use the association.build method.

If either of these saves fails due to validation errors, then the assignment statement returns false and the assignment itself is cancelled.

If the parent object (the one declaring the has_one association) is unsaved (that is, new_record? returns true) then the child objects are not saved.

If you want to assign an object to a has_one association without saving the object, use the association.build method.

4.3. The has_many Association

The has_many association creates a one-to-many relationship with another model. In database terms, this association says that the other class will have a foreign key that refers to instances of this class.

4.3.1. Methods Added

When you declare a has_many association, the declaring class automatically gains 13 methods related to the association:

collection(force_reload = false) @@ -1498,12 +1271,12 @@ http://www.gnu.org/software/src-highlite -->
-collection<<(object, …) +collection<<(object, ...)
-collection.delete(object, …) +collection.delete(object, ...)
@@ -1513,12 +1286,12 @@ http://www.gnu.org/software/src-highlite -->
-collection_singular_ids +collection\_singular\_ids
-collection_singular_ids=ids +collection\_singular\_ids=ids
@@ -1538,17 +1311,17 @@ http://www.gnu.org/software/src-highlite -->
-collection.find(…) +collection.find(...)
-collection.exist?(…) +collection.exist?(...)
-collection.build(attributes = {}, …) +collection.build(attributes = {}, ...)
@@ -1557,7 +1330,7 @@ http://www.gnu.org/software/src-highlite -->

In all of these methods, collection is replaced with the symbol passed as the first argument to has_many, and collection_singular is replaced with the singularized version of that symbol.. For example, given the declaration:

In all of these methods, collection is replaced with the symbol passed as the first argument to has_many, and collection\_singular is replaced with the singularized version of that symbol.. For example, given the declaration:

class Customer < ActiveRecord::Base
   has_many :orders
-end
-

Each instance of the customer model will have these methods:

end

Each instance of the customer model will have these methods:

@orders = @customer.orders
-

`collection<<(object, …)`

The collection<< method adds one or more objects to the collection by setting their foreign keys to the primary key of the calling model.

@orders = @customer.orders

`collection<<(object, ...)`

The collection<< method adds one or more objects to the collection by setting their foreign keys to the primary key of the calling model.

@customer.orders << @order1
-

`collection.delete(object, …)`

The collection.delete method removes one or more objects from the collection by setting their foreign keys to NULL.

@customer.orders << @order1

`collection.delete(object, ...)`

The collection.delete method removes one or more objects from the collection by setting their foreign keys to NULL.

@customer.orders.delete(@order1)
-

@customer.orders.delete(@order1)

- +

Objects will be in addition destroyed if they're associated with :dependent ⇒ :destroy, and deleted if they're associated with :dependent ⇒ :delete_all. Objects will be in addition destroyed if they’re associated with :dependent => :destroy, and deleted if they’re associated with :dependent => :delete_all.

`collection=objects`

The collection= method makes the collection contain only the supplied objects, by adding and deleting as appropriate.

`collection_singular_ids`

The collection_singular_ids method returns an array of the ids of the objects in the collection.

The collection= method makes the collection contain only the supplied objects, by adding and deleting as appropriate.

`collection\_singular\_ids`

The collection\_singular\_ids method returns an array of the ids of the objects in the collection.

@order_ids = @customer.order_ids
-

`_collection_singular_ids=ids`

The _collection_singular_ids= method makes the collection contain only the objects identified by the supplied primary key values, by adding and deleting as appropriate.

@order_ids = @customer.order_ids

`_collection\_singular\_ids=ids`

The _collection\_singular\_ids= method makes the collection contain only the objects identified by the supplied primary key values, by adding and deleting as appropriate.

`collection.clear`

The collection.clear method removes every object from the collection. This destroys the associated objects if they are associated with :dependent ⇒ :destroy, deletes them directly from the database if :dependent ⇒ :delete_all, and otherwise sets their foreign keys to NULL.

The collection.clear method removes every object from the collection. This destroys the associated objects if they are associated with :dependent => :destroy, deletes them directly from the database if :dependent => :delete_all, and otherwise sets their foreign keys to NULL.

`collection.empty?`

The collection.empty? method returns true if the collection does not contain any associated objects.

<% if @customer.orders.empty? %>
   No Orders Found
-<% end %>
-

+<% end %>

`collection.size`

The collection.size method returns the number of objects in the collection.

@order_count = @customer.orders.size
-

`collection.find(…)`

The collection.find method finds objects within the collection. It uses the same syntax and options as ActiveRecord::Base.find.

@order_count = @customer.orders.size

`collection.find(...)`

The collection.find method finds objects within the collection. It uses the same syntax and options as ActiveRecord::Base.find.

@open_orders = @customer.orders.find(:all, :conditions => "open = 1")
-

`collection.exist?(…)`

The collection.exist? method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as ActiveRecord::Base.exists?.

`collection.build(attributes = {}, …)`

The collection.build method returns one or more new objects of the associated type. These objects will be instantiated from the passed attributes, and the link through their foreign key will be created, but the associated objects will not yet be saved.

@open_orders = @customer.orders.find(:all, :conditions => "open = 1")

`collection.exist?(...)`

The collection.exist? method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as ActiveRecord::Base.exists?.

`collection.build(attributes = {}, ...)`

@order = @customer.orders.build({:order_date => Time.now, :order_number => "A12345"})
-

@order = @customer.orders.build({:order_date => Time.now, :order_number => "A12345"})

`collection.create(attributes = {})`

The collection.create method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through its foreign key will be created, and the associated object will be saved (assuming that it passes any validations).

@order = @customer.orders.create({:order_date => Time.now, :order_number => "A12345"})
-

@order = @customer.orders.create({:order_date => Time.now, :order_number => "A12345"})

4.3.2. Options for has_many

In many situations, you can use the default behavior for has_many without any customization. But you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a has_many association. For example, an association with several options might look like this:

class Customer < ActiveRecord::Base
   has_many :orders, :dependent => :delete_all, :validate => :false
-end
-

The has_many association supports these options:

end

The has_many association supports these options:

:as @@ -1806,9 +1567,9 @@ http://www.gnu.org/software/src-highlite -->

`:as`

Setting the :as option indicates that this is a polymorphic association, as discussed earlier in this guide.

`:class_name`

If the name of the other model cannot be derived from the association name, you can use the :class_name option to supply the model name. For example, if a customer has many orders, but the actual name of the model containing orders is Transaction, you'd set things up this way:

class Customer < ActiveRecord::Base
   has_many :orders, :class_name => "Transaction"
-end
-

+end

`:conditions`

The :conditions option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL WHERE clause).

class Customer < ActiveRecord::Base
   has_many :confirmed_orders, :class_name => "Order", :conditions => "confirmed = 1"
-end
-

You can also set conditions via a hash:

+end +

You can also set conditions via a hash:

class Customer < ActiveRecord::Base
   has_many :confirmed_orders, :class_name => "Order", :conditions => { :confirmed => true }
-end
-

If you use a hash-style :conditions option, then record creation via this association will be automatically scoped using the hash. In this case, using @customer.confirmed_orders.create or @customer.confirmed_orders.build will create orders where the confirmed column has the value true.

+end +

`:counter_sql`

Normally Rails automatically generates the proper SQL to count the association members. With the :counter_sql option, you can specify a complete SQL statement to count them yourself.

- +

If you specify :finder_sql but not :counter_sql, then the counter SQL will be generated by substituting SELECT COUNT(*) FROM for the SELECT … FROM clause of your :finder_sql statement. If you specify :finder_sql but not :counter_sql, then the counter SQL will be generated by substituting SELECT COUNT(*) FROM for the SELECT ... FROM clause of your :finder_sql statement.

`:dependent`

If you set the :dependent option to :destroy, then deleting this object will call the destroy method on the associated objects to delete those objects. If you set the :dependent option to :delete_all, then deleting this object will delete the associated objects without calling their destroy method. If you set the :dependent option to :nullify, then deleting this object will set the foreign key in the associated objects to NULL.

@@ -1861,11 +1619,11 @@ http://www.gnu.org/software/src-highlite -->

`:extend`

The :extend option specifies a named module to extend the association proxy. Association extensions are discussed in detail later in this guide.

`:finder_sql`

Normally Rails automatically generates the proper SQL to fetch the association members. With the :finder_sql option, you can specify a complete SQL statement to fetch them yourself. If fetching objects requires complex multi-table SQL, this may be necessary.

`:foreign_key`

class Customer < ActiveRecord::Base
   has_many :orders, :foreign_key => "cust_id"
-end
-

+end

@@ -1884,7 +1641,7 @@ http://www.gnu.org/software/src-highlite -->

`:group`

The :group option supplies an attribute name to group the result set by, using a GROUP BY clause in the finder SQL.

class Customer < ActiveRecord::Base
   has_many :line_items, :through => :orders, :group => "orders.id"
-end
-

+end

`:include`

You can use the :include option to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models:

end class LineItem < ActiveRecord::Base belongs_to :order -end -

If you frequently retrieve line items directly from customers (@customer.orders.line_items), then you can make your code somewhat more efficient by including line items in the association from customers to orders:

+end +

end class LineItem < ActiveRecord::Base belongs_to :order -end -

+end

`:limit`

The :limit option lets you restrict the total number of objects that will be fetched through an association.

class Customer < ActiveRecord::Base
   has_many :recent_orders, :class_name => "Order", :order => "order_date DESC", :limit => 100
-end
-

+end

`:offset`

The :offset option lets you specify the starting offset for fetching objects via an association. For example, if you set :offset ⇒ 11, it will skip the first 11 records.

The :offset option lets you specify the starting offset for fetching objects via an association. For example, if you set :offset => 11, it will skip the first 11 records.

`:order`

The :order option dictates the order in which associated objects will be received (in the syntax used by a SQL ORDER BY clause).

class Customer < ActiveRecord::Base
   has_many :orders, :order => "date_confirmed DESC"
-end
-

+end

`:primary_key`

By convention, Rails guesses that the column used to hold the primary key of this model is id. You can override this and explicitly specify the primary key with the :primary_key option.

`:readonly`

If you set the :readonly option to true, then the associated objects will be read-only when retrieved via the association.

`:select`

The :select option lets you override the SQL SELECT clause that is used to retrieve data about the associated objects. By default, Rails retrieves all columns.

@@ -1968,25 +1720,25 @@ http://www.gnu.org/software/src-highlite -->

`:source`

The :source option specifies the source association name for a has_many :through association. You only need to use this option if the name of the source association cannot be automatically inferred from the association name.

`:source_type`

The :source_type option specifies the source association type for a has_many :through association that proceeds through a polymorphic association.

`:through`

The :through option specifies a join model through which to perform the query. has_many :through associations provide a way to implement many-to-many relationships, as discussed earlier in this guide.

`:uniq`

Specify the :uniq ⇒ true option to remove duplicates from the collection. This is most useful in conjunction with the :through option.

Specify the :uniq => true option to remove duplicates from the collection. This is most useful in conjunction with the :through option.

`:validate`

If you set the :validate option to false, then associated objects will not be validated whenever you save this object. By default, this is true: associated objects will be validated when this object is saved.

4.3.3. When are Objects Saved?

When you assign an object to a has_many association, that object is automatically saved (in order to update its foreign key). If you assign multiple objects in one statement, then they are all saved.

If any of these saves fails due to validation errors, then the assignment statement returns false and the assignment itself is cancelled.

If the parent object (the one declaring the has_many association) is unsaved (that is, new_record? returns true) then the child objects are not saved when they are added. All unsaved members of the association will automatically be saved when the parent is saved.

If you want to assign an object to a has_many association without saving the object, use the collection.build method.

If any of these saves fails due to validation errors, then the assignment statement returns false and the assignment itself is cancelled.

If you want to assign an object to a has_many association without saving the object, use the collection.build method.

4.4. The `has_and_belongs_to_many` Association

The has_and_belongs_to_many association creates a many-to-many relationship with another model. In database terms, this associates two classes via an intermediate join table that includes foreign keys referring to each of the classes.

4.4.1. Methods Added

When you declare a has_and_belongs_to_many association, the declaring class automatically gains 13 methods related to the association:

collection(force_reload = false) @@ -1994,12 +1746,12 @@ http://www.gnu.org/software/src-highlite -->
-collection<<(object, …) +collection<<(object, ...)
-collection.delete(object, …) +collection.delete(object, ...)
@@ -2009,12 +1761,12 @@ http://www.gnu.org/software/src-highlite -->
-collection_singular_ids +collection\_singular\_ids
-collection_singular_ids=ids +collection\_singular\_ids=ids
@@ -2034,12 +1786,12 @@ http://www.gnu.org/software/src-highlite -->
-collection.find(…) +collection.find(...)
-collection.exist?(…) +collection.exist?(...)
@@ -2053,7 +1805,7 @@ http://www.gnu.org/software/src-highlite -->

class Part < ActiveRecord::Base
   has_and_belongs_to_many :assemblies
-end
-

Each instance of the part model will have these methods:

end

Each instance of the part model will have these methods:

@assemblies = @part.assemblies
-

`collection<<(object, …)`

The collection<< method adds one or more objects to the collection by creating records in the join table.

@assemblies = @part.assemblies

`collection<<(object, ...)`

The collection<< method adds one or more objects to the collection by creating records in the join table.

@part.assemblies << @assembly1
-

@part.assemblies << @assembly1

@@ -2119,33 +1867,31 @@ http://www.gnu.org/software/src-highlite --> This method is aliased as collection.concat and collection.push.

`collection.delete(object, …)`

The collection.delete method removes one or more objects from the collection by deleting records in the join table. This does not destroy the objects.

`collection.delete(object, ...)`

The collection.delete method removes one or more objects from the collection by deleting records in the join table. This does not destroy the objects.

@part.assemblies.delete(@assembly1)
-

@part.assemblies.delete(@assembly1)

`collection=objects`

The collection= method makes the collection contain only the supplied objects, by adding and deleting as appropriate.

`collection_singular_ids`

# Returns an array of the associated objects' ids

The collection_singular_ids method returns an array of the ids of the objects in the collection.

The collection= method makes the collection contain only the supplied objects, by adding and deleting as appropriate.

`collection\_singular\_ids`

# Returns an array of the associated objects' ids

The collection\_singular\_ids method returns an array of the ids of the objects in the collection.

@assembly_ids = @part.assembly_ids
-

`collection_singular_ids=ids`

The collection_singular_ids= method makes the collection contain only the objects identified by the supplied primary key values, by adding and deleting as appropriate.

@assembly_ids = @part.assembly_ids

`collection\_singular\_ids=ids`

The collection\_singular\_ids= method makes the collection contain only the objects identified by the supplied primary key values, by adding and deleting as appropriate.

`collection.clear`

The collection.clear method removes every object from the collection by deleting the rows from the joining tableassociation. This does not destroy the associated objects.

`collection.empty?`

The collection.empty? method returns true if the collection does not contain any associated objects.

<% if @part.assemblies.empty? %>
   This part is not used in any assemblies
-<% end %>
-

+<% end %>

`collection.size`

The collection.size method returns the number of objects in the collection.

@assembly_count = @part.assemblies.size
-

`collection.find(…)`

The collection.find method finds objects within the collection. It uses the same syntax and options as ActiveRecord::Base.find. It also adds the additional condition that the object must be in the collection.

@assembly_count = @part.assemblies.size

`collection.find(...)`

@new_assemblies = @part.assemblies.find(:all, :conditions => ["created_at > ?", 2.days.ago])
-

`collection.exist?(…)`

The collection.exist? method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as ActiveRecord::Base.exists?.

`collection.build(attributes = {})`

The collection.build method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through the join table will be created, but the associated object will not yet be saved.

@new_assemblies = @part.assemblies.find(:all, :conditions => ["created_at > ?", 2.days.ago])

`collection.exist?(...)`

The collection.exist? method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as ActiveRecord::Base.exists?.

`collection.build(attributes = {})`

@assembly = @part.assemblies.build({:assembly_name => "Transmission housing"})
-

@assembly = @part.assemblies.build({:assembly_name => "Transmission housing"})

`collection.create(attributes = {})`

The collection.create method returns a new object of the associated type. This objects will be instantiated from the passed attributes, the link through the join table will be created, and the associated object will be saved (assuming that it passes any validations).

@assembly = @part.assemblies.create({:assembly_name => "Transmission housing"})
-

@assembly = @part.assemblies.create({:assembly_name => "Transmission housing"})

4.4.2. Options for has_and_belongs_to_many

In many situations, you can use the default behavior for has_and_belongs_to_many without any customization. But you can alter that behavior in a number of ways. This section cover the options that you can pass when you create a has_and_belongs_to_many association. For example, an association with several options might look like this:

class Parts < ActiveRecord::Base
   has_and_belongs_to_many :assemblies, :uniq => true, :read_only => true
-end
-

The has_and_belongs_to_many association supports these options:

end

The has_and_belongs_to_many association supports these options:

:association_foreign_key @@ -2303,7 +2043,7 @@ http://www.gnu.org/software/src-highlite -->

`:association_foreign_key`

By convention, Rails guesses that the column in the join table used to hold the foreign key pointing to the other model is the name of that model with the suffix _id added. The :association_foreign_key option lets you set the name of the foreign key directly:

@@ -2320,10 +2060,9 @@ http://www.gnu.org/software/src-highlite -->

class User < ActiveRecord::Base
   has_and_belongs_to_many :friends, :class_name => "User",
     :foreign_key => "this_user_id", :association_foreign_key => "other_user_id"
-end
-

+end

`:class_name`

If the name of the other model cannot be derived from the association name, you can use the :class_name option to supply the model name. For example, if a part has many assemblies, but the actual name of the model containing assemblies is Gadget, you'd set things up this way:

class Parts < ActiveRecord::Base
   has_and_belongs_to_many :assemblies, :class_name => "Gadget"
-end
-

+end

`:conditions`

The :conditions option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL WHERE clause).

class Parts < ActiveRecord::Base
   has_and_belongs_to_many :assemblies, :conditions => "factory = 'Seattle'"
-end
-

You can also set conditions via a hash:

+end +

You can also set conditions via a hash:

class Parts < ActiveRecord::Base
   has_and_belongs_to_many :assemblies, :conditions => { :factory => 'Seattle' }
-end
-

If you use a hash-style :conditions option, then record creation via this association will be automatically scoped using the hash. In this case, using @parts.assemblies.create or @parts.assemblies.build will create orders where the factory column has the value "Seattle".

+end +

`:counter_sql`

Normally Rails automatically generates the proper SQL to count the association members. With the :counter_sql option, you can specify a complete SQL statement to count them yourself.

- +

`:delete_sql`

Normally Rails automatically generates the proper SQL to remove links between the associated classes. With the :delete_sql option, you can specify a complete SQL statement to delete them yourself.

`:extend`

The :extend option specifies a named module to extend the association proxy. Association extensions are discussed in detail later in this guide.

`:finder_sql`

`:foreign_key`

By convention, Rails guesses that the column in the join table used to hold the foreign key pointing to this model is the name of this model with the suffix _id added. The :foreign_key option lets you set the name of the foreign key directly:

class User < ActiveRecord::Base
   has_and_belongs_to_many :friends, :class_name => "User",
     :foreign_key => "this_user_id", :association_foreign_key => "other_user_id"
-end
-

+end

`:group`

The :group option supplies an attribute name to group the result set by, using a GROUP BY clause in the finder SQL.

class Parts < ActiveRecord::Base
   has_and_belongs_to_many :assemblies, :group => "factory"
-end
-

+end

`:include`

You can use the :include option to specify second-order associations that should be eager-loaded when this association is used.

`:insert_sql`

Normally Rails automatically generates the proper SQL to create links between the associated classes. With the :insert_sql option, you can specify a complete SQL statement to insert them yourself.

`:join_table`

If the default name of the join table, based on lexical ordering, is not what you want, you can use the :join_table option to override the default.

`:limit`

The :limit option lets you restrict the total number of objects that will be fetched through an association.

class Parts < ActiveRecord::Base
   has_and_belongs_to_many :assemblies, :order => "created_at DESC", :limit => 50
-end
-

+end

`:offset`

The :offset option lets you specify the starting offset for fetching objects via an association. For example, if you set :offset ⇒ 11, it will skip the first 11 records.

The :offset option lets you specify the starting offset for fetching objects via an association. For example, if you set :offset => 11, it will skip the first 11 records.

`:order`

The :order option dictates the order in which associated objects will be received (in the syntax used by a SQL ORDER BY clause).

class Parts < ActiveRecord::Base
   has_and_belongs_to_many :assemblies, :order => "assembly_name ASC"
-end
-

+end

`:readonly`

If you set the :readonly option to true, then the associated objects will be read-only when retrieved via the association.

`:select`

The :select option lets you override the SQL SELECT clause that is used to retrieve data about the associated objects. By default, Rails retrieves all columns.

`:uniq`

Specify the :uniq ⇒ true option to remove duplicates from the collection.

Specify the :uniq => true option to remove duplicates from the collection.

`:validate`

4.4.3. When are Objects Saved?

When you assign an object to a has_and_belongs_to_many association, that object is automatically saved (in order to update the join table). If you assign multiple objects in one statement, then they are all saved.

If any of these saves fails due to validation errors, then the assignment statement returns false and the assignment itself is cancelled.

If the parent object (the one declaring the has_and_belongs_to_many association) is unsaved (that is, new_record? returns true) then the child objects are not saved when they are added. All unsaved members of the association will automatically be saved when the parent is saved.

If you want to assign an object to a has_and_belongs_to_many association without saving the object, use the collection.build method.

If any of these saves fails due to validation errors, then the assignment statement returns false and the assignment itself is cancelled.

If you want to assign an object to a has_and_belongs_to_many association without saving the object, use the collection.build method.

4.5. Association Callbacks

Normal callbacks hook into the lifecycle of Active Record objects, allowing you to work with those objects at various points. For example, you can use a :before_save callback to cause something to happen just before an object is saved.

Association callbacks are similar to normal callbacks, but they are triggered by events in the lifecycle of a collection. There are four available association callbacks:

before_add @@ -2462,7 +2194,7 @@ http://www.gnu.org/software/src-highlite -->

You define association callbacks by adding options to the association declaration. For example:

def check_credit_limit(order) ... end -end -

Rails passes the object being added or removed to the callback.

You can stack callbacks on a single event by passing them as an array:

end

Rails passes the object being added or removed to the callback.

You can stack callbacks on a single event by passing them as an array:

def calculate_shipping_charges(order) ... end -end -

If a before_add callback throws an exception, the object does not get added to the collection. Similarly, if a before_remove callback throws an exception, the object does not get removed from the collection.

+end +

4.6. Association Extensions

You're not limited to the functionality that Rails automatically builds into association proxy objects. You can also extend these objects through anonymous modules, adding new finders, creators, or other methods. For example:

You’re not limited to the functionality that Rails automatically builds into association proxy objects. You can also extend these objects through anonymous modules, adding new finders, creators, or other methods. For example:

find_by_region_id(order_number[0..2]) end end -end -

If you have an extension that should be shared by many associations, you can use a named extension module. For example:

+end +

If you have an extension that should be shared by many associations, you can use a named extension module. For example:

class Supplier < ActiveRecord::Base has_many :deliveries, :extend => FindRecentExtension -end -

To include more than one extension module in a single association, specify an array of names:

+end +

To include more than one extension module in a single association, specify an array of names:

class Customer < ActiveRecord::Base
   has_many :orders, :extend => [FindRecentExtension, FindActiveExtension]
-end
-

Extensions can refer to the internals of the association proxy using these three accessors:

end

Extensions can refer to the internals of the association proxy using these three accessors:

proxy_owner returns the object that the association is a part of. @@ -2562,8 +2289,8 @@ http://www.gnu.org/software/src-highlite -->

5. Changelog

Lighthouse ticket

September 28, 2008: Corrected has_many :through diagram, added polymorphic diagram, some reorganization by Mike Gunderloy . First release version. @@ -2582,7 +2309,7 @@ September 14, 2008: initial version by Mike

- + + diff --git a/railties/doc/guides/html/authors.html b/railties/doc/guides/html/authors.html index 6fd556d2cd..ab205c96a9 100644 --- a/railties/doc/guides/html/authors.html +++ b/railties/doc/guides/html/authors.html @@ -1,245 +1,87 @@ - - About the Authors - - - - - + + About the Authors + + + + - - -

- -

About the Authors

+ + +

+ +

About the Authors

Frederick Cheung is Chief Wizard at Texperts where he has been using Rails since 2006. +

Frederick Cheung is Chief Wizard at Texperts where he has been using Rails since 2006. He is based in Cambridge (UK) and when not consuming fine ales he blogs at spacevatican.org.

Mike Gunderloy is an independent consultant who brings 25 years of experience in a variety of languages to bear on his current +

Mike Gunderloy is an independent consultant who brings 25 years of experience in a variety of languages to bear on his current work with Rails. His near-daily links and other blogging can be found at A Fresh Cup.

Emilio Tagua — a.k.a. miloops — is an Argentinian entrepreneur, developer, open source contributor and Rails evangelist. +

Emilio Tagua — a.k.a. miloops — is an Argentinian entrepreneur, developer, open source contributor and Rails evangelist. Cofounder of Eventioz. He has been using Rails since 2006 and contributing since early 2008. Can be found at gmail, twitter, freenode, everywhere as miloops.

Heiko Webers is the founder of bauland42, a German web application security consulting and development +

Heiko Webers is the founder of bauland42, a German web application security consulting and development company focused on Ruby on Rails. He blogs at http://www.rorsecurity.info. After 10 years of desktop application development, Heiko has rarely looked back.

Tore Darell is an independent developer based in Menton, France who specialises in cruft-free web applications using Ruby, Rails +

Tore Darell is an independent developer based in Menton, France who specialises in cruft-free web applications using Ruby, Rails and unobtrusive JavaScript. His home on the internet is his blog Sneaky Abstractions.

Jeff Dean is a software engineer with Pivotal Labs.

+ +

Cássio Marques is a Brazilian software developer working with different programming languages such as Ruby, JavaScript, C++ and Java, as an independent consultant. He blogs at http://cassiomarques.wordpress.com, which is mainly written in portuguese, but will soon get a new section for posts with english translation.

+ +

Pratik Naik is an independent Ruby on Rails consultant and also a member of the Rails core team. He blogs semi-regularly at has_many :bugs, :through => :rails and has an active twitter account .

diff --git a/railties/doc/guides/html/benchmarking_and_profiling.html b/railties/doc/guides/html/benchmarking_and_profiling.html deleted file mode 100644 index 9bd1c10dc8..0000000000 --- a/railties/doc/guides/html/benchmarking_and_profiling.html +++ /dev/null @@ -1,1018 +0,0 @@ - - - - - Benchmarking and Profiling Rails - - - - - - - - - -

- - - -

Benchmarking and Profiling Rails

This guide covers the benchmarking and profiling tactics/tools of Rails and Ruby in general. By referring to this guide, you will be able to:

-
-Understand the various types of benchmarking and profiling metrics -
-
-
-Generate performance/benchmarking tests -
-
-
-Use GC patched Ruby binary to measure memory usage and object allocation -
-
-
-Understand the information provided by Rails inside the log files -
-
-
-Learn about various tools facilitating benchmarking and profiling -
-

1. Why Benchmark and Profile ?

Benchmarking and Profiling is an integral part of the development cycle. It is very important that you don't make your end users wait for too long before the page is completely loaded. Ensuring a plesant browsing experience to the end users and cutting cost of unnecessary hardwares is important for any web application.

1.1. What is the difference between benchmarking and profiling ?

Benchmarking is the process of finding out if a piece of code is slow or not. Whereas profiling is the process of finding out what exactly is slowing down that piece of code.

2. Using and understanding the log files

Rails logs files containt basic but very useful information about the time taken to serve every request. A typical log entry looks something like :

Processing ItemsController#index (for 127.0.0.1 at 2008-10-17 00:08:18) [GET]
-  Session ID: BAh7BiIKZmxhc2hJQzonQWN0aHsABjoKQHVzZWR7AA==--83cff4fe0a897074a65335
-  Parameters: {"action"=>"index", "controller"=>"items"}
-Rendering template within layouts/items
-Rendering items/index
-Completed in 5ms (View: 2, DB: 0) | 200 OK [http://localhost/items]
-

For this section, we're only interested in the last line from that log entry:

Completed in 5ms (View: 2, DB: 0) | 200 OK [http://localhost/items]
-

This data is fairly straight forward to understand. Rails uses millisecond(ms) as the metric to measures the time taken. The complete request spent 5 ms inside Rails, out of which 2 ms were spent rendering views and none was spent communication with the database. It's safe to assume that the remaining 3 ms were spent inside the controller.

3. Helper methods

Rails provides various helper methods inside Active Record, Action Controller and Action View to measure the time taken by a specific code. The method is called benchmark() in all three components.

Project.benchmark("Creating project") do
-  project = Project.create("name" => "stuff")
-  project.create_manager("name" => "David")
-  project.milestones << Milestone.find(:all)
-end
-

The above code benchmarks the multiple statments enclosed inside Project.benchmark("Creating project") do..end block and prints the results inside log files. The statement inside log files will look like:

Creating projectem (185.3ms)
-

Please refer to API docs for optional options to benchmark()

Similarly, you could use this helper method inside controllers ( Note that it's a class method here ):

def process_projects
-  self.class.benchmark("Processing projects") do
-    Project.process(params[:project_ids])
-    Project.update_cached_projects
-  end
-end
-

and views:

<% benchmark("Showing projects partial") do %>
-  <%= render :partial => @projects %>
-<% end %>
-

4. Performance Test Cases

Rails provides a very easy to write performance test cases, which look just like the regular integration tests.

If you have a look at test/performance/browsing_test.rb in a newly created Rails application:

require 'test_helper'
-require 'performance_test_help'
-
-# Profiling results for each test method are written to tmp/performance.
-class BrowsingTest < ActionController::PerformanceTest
-  def test_homepage
-    get '/'
-  end
-end
-

This is an automatically generated example performance test file, for testing performance of homepage(/) of the application.

4.1. Modes

4.1.1. Benchmarking

4.1.2. Profiling

4.2. Metrics

4.2.1. Process Time

CPU Cycles.

4.2.2. Memory

Memory taken.

4.2.3. Objects

Objects allocated.

4.2.4. GC Runs

Number of times the Ruby GC was run.

4.2.5. GC Time

Time spent running the Ruby GC.

4.3. Preparing Ruby and Ruby-prof

Before we go ahead, Rails performance testing requires you to build a special Ruby binary with some super powers - GC patch for measuring GC Runs/Time. This process is very straight forward. If you've never compiled a Ruby binary before, you can follow the following steps to build a ruby binary inside your home directory:

4.3.1. Compile

[lifo@null ~]$ mkdir rubygc
-[lifo@null ~]$ wget ftp://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.6-p111.tar.gz
-[lifo@null ~]$ tar -xzvf ruby-1.8.6-p111.tar.gz
-[lifo@null ~]$ cd ruby-1.8.6-p111
-[lifo@null ruby-1.8.6-p111]$ curl http://rubyforge.org/tracker/download.php/1814/7062/17676/3291/ruby186gc.patch | patch -p0
-[lifo@null ruby-1.8.6-p111]$ ./configure --prefix=/Users/lifo/rubygc
-[lifo@null ruby-1.8.6-p111]$ make && make install
-

4.3.2. Prepare aliases

Add the following lines in your ~/.profile for convenience:

alias gcruby='/Users/lifo/rubygc/bin/ruby'
-alias gcrake='/Users/lifo/rubygc/bin/rake'
-alias gcgem='/Users/lifo/rubygc/bin/gem'
-alias gcirb='/Users/lifo/rubygc/bin/irb'
-alias gcrails='/Users/lifo/rubygc/bin/rails'

4.3.3. Install rubygems and some basic gems

[lifo@null ~]$ wget http://rubyforge.org/frs/download.php/38646/rubygems-1.2.0.tgz
-[lifo@null ~]$ tar -xzvf rubygems-1.2.0.tgz
-[lifo@null ~]$ cd rubygems-1.2.0
-[lifo@null rubygems-1.2.0]$ gcruby setup.rb
-[lifo@null rubygems-1.2.0]$ cd ~
-[lifo@null ~]$ gcgem install rake
-[lifo@null ~]$ gcgem install rails

4.3.4. Install MySQL gem

[lifo@null ~]$ gcgem install mysql

If this fails, you can try to install it manually:

[lifo@null ~]$ cd /Users/lifo/rubygc/lib/ruby/gems/1.8/gems/mysql-2.7/
-[lifo@null mysql-2.7]$ gcruby extconf.rb --with-mysql-config
-[lifo@null mysql-2.7]$ make && make install

4.4. Installing Jeremy Kemper's ruby-prof

We also need to install Jeremy's ruby-prof gem using our newly built ruby:

[lifo@null ~]$ git clone git://github.com/jeremy/ruby-prof.git
-[lifo@null ~]$ cd ruby-prof/
-[lifo@null ruby-prof (master)]$ gcrake gem
-[lifo@null ruby-prof (master)]$ gcgem install pkg/ruby-prof-0.6.1.gem
-

4.5. Generating performance test

Rails provides a simple generator for creating new performance tests:

[lifo@null application (master)]$ script/generate performance_test homepage
-

This will generate test/performance/homepage_test.rb:

require 'test_helper'
-require 'performance_test_help'
-
-class HomepageTest < ActionController::PerformanceTest
-  # Replace this with your real tests.
-  def test_homepage
-    get '/'
-  end
-end
-

Which you can modify to suit your needs.

4.6. Running tests

5. Understanding Performance Tests Outputs

5.1. Our First Performance Test

So how do we profile a request.

One of the things that is important to us is how long it takes to render the home page - so let's make a request to the home page. Once the request is complete, the results will be outputted in the terminal.

In the terminal run

[User profiling_tester]$ gcruby tests/performance/homepage.rb
-

After the tests runs for a few seconds you should see something like this.

HomepageTest#test_homepage (19 ms warmup)
-        process_time: 26 ms
-              memory: 298.79 KB
-             objects: 1917
-
-Finished in 2.207428 seconds.

Simple but efficient.

-
-Process Time refers to amount of time necessary to complete the action. -
-
-
-memory is the amount of information loaded into memory -
-
-
-object ??? #TODO find a good definition. Is it the amount of objects put into a ruby heap for this process? -
-

In addition we also gain three types of itemized log files for each of these outputs. They can be found in your tmp directory of your application.

The Three types are

-
-Flat File - A simple text file with the data laid out in a grid -
-
-
-Graphical File - A html colored coded version of the simple text file with hyperlinks between the various methods. Most useful is the bolding of the main processes for each portion of the action. -
-
-
-Tree File - A file output that can be use in conjunction with KCachegrind to visualize the process -
-

- - - -

- -	KCachegrind is Linux only. For Mac this means you have to do a full KDE install to have it working in your OS. Which is over 3 gigs in size. For windows there is clone called wincachegrind but it is no longer actively being developed.

Below are examples for Flat Files and Graphical Files

5.2. Flat Files

Example: Flat File Output Processing Time

Thread ID: 2279160 -Total: 0.026097

%self     total     self     wait    child    calls  name
- 6.41      0.06     0.04     0.00     0.02      571  Kernel#===
- 3.17      0.00     0.00     0.00     0.00      172  Hash#[]
- 2.42      0.00     0.00     0.00     0.00       13  MonitorMixin#mon_exit
- 2.05      0.00     0.00     0.00     0.00       15  Array#each
- 1.56      0.00     0.00     0.00     0.00        6  Logger#add
- 1.55      0.00     0.00     0.00     0.00       13  MonitorMixin#mon_enter
- 1.36      0.03     0.00     0.00     0.03        1  ActionController::Integration::Session#process
- 1.31      0.00     0.00     0.00     0.00       13  MonitorMixin#mon_release
- 1.15      0.00     0.00     0.00     0.00        8  MonitorMixin#synchronize-1
- 1.09      0.00     0.00     0.00     0.00       23  Class#new
- 1.03      0.01     0.00     0.00     0.01        5  MonitorMixin#synchronize
- 0.89      0.00     0.00     0.00     0.00       74  Hash#default
- 0.89      0.00     0.00     0.00     0.00        6  Hodel3000CompliantLogger#format_message
- 0.80      0.00     0.00     0.00     0.00        9  c
- 0.80      0.00     0.00     0.00     0.00       11  ActiveRecord::ConnectionAdapters::ConnectionHandler#retrieve_connection_pool
- 0.79      0.01     0.00     0.00     0.01        1  ActionController::Benchmarking#perform_action_without_rescue
- 0.18      0.00     0.00     0.00     0.00       17  <Class::Object>#allocate

So what do these columns tell us:

-
-%self - The percentage of time spent processing the method. This is derived from self_time/total_time -
-
-
-total - The time spent in this method and its children. -
-
-
-self - The time spent in this method. -
-
-
-wait - Time processed was queued -
-
-
-child - The time spent in this method's children. -
-
-
-calls - The number of times this method was called. -
-
-
-name - The name of the method. -
-

Name can be displayed three seperate ways: - #toplevel - The root method that calls all other methods - MyObject#method - Example Hash#each, The class Hash is calling the method each - * <Object:MyObject>#test - The <> characters indicate a singleton method on a singleton class. Example <Class::Object>#allocate

Methods are sorted based on %self. Hence the ones taking the most time and resources will be at the top.

So for Array#each which is calling each on the class array. We find that it processing time is 2% of the total and was called 15 times. The rest of the information is 0.00 because the process is so fast it isn't recording times less then 100 ms.

Example: Flat File Memory Output

Thread ID: 2279160 -Total: 509.724609

%self     total     self     wait    child    calls  name
- 4.62     23.57    23.57     0.00     0.00       34  String#split
- 3.95     57.66    20.13     0.00    37.53        3  <Module::YAML>#quick_emit
- 2.82     23.70    14.35     0.00     9.34        2  <Module::YAML>#quick_emit-1
- 1.37     35.87     6.96     0.00    28.91        1  ActionView::Helpers::FormTagHelper#form_tag
- 1.35      7.69     6.88     0.00     0.81        1  ActionController::HttpAuthentication::Basic::ControllerMethods#authenticate_with_http_basic
- 1.06      6.09     5.42     0.00     0.67       90  String#gsub
- 1.01      5.13     5.13     0.00     0.00       27  Array#-

Very similar to the processing time format. The main difference here is that instead of calculating time we are now concerned with the amount of KB put into memory (or is it strictly into the heap) can I get clarification on this minor point?

So for <Module::YAML>#quick_emit which is singleton method on the class YAML it uses 57.66 KB in total, 23.57 through its own actions, 6.69 from actions it calls itself and that it was called twice.

Example: Flat File Objects

Thread ID: 2279160 -Total: 6537.000000

%self     total     self     wait    child    calls  name
-15.16   1096.00   991.00     0.00   105.00       66  Hash#each
- 5.25    343.00   343.00     0.00     0.00        4  Mysql::Result#each_hash
- 4.74   2203.00   310.00     0.00  1893.00       42  Array#each
- 3.75   4529.00   245.00     0.00  4284.00        1  ActionView::Base::CompiledTemplates#_run_erb_47app47views47layouts47application46html46erb
- 2.00    136.00   131.00     0.00     5.00       90  String#gsub
- 1.73    113.00   113.00     0.00     0.00       34  String#split
- 1.44    111.00    94.00     0.00    17.00       31  Array#each-1

#TODO Find correct terminology for how to describe what this is exactly profiling as in are there really 2203 array objects or 2203 pointers to array objects?.

5.3. Graph Files

While the information gleamed from flat files is very useful we still don't know which processes each method is calling. We only know how many. This is not true for a graph file. Below is a text representation of a graph file. The actual graph file is an html entity and an example of which can be found Here

#TODO (Handily the graph file has links both between it many processes and to the files that actually contain them for debugging. - )

Example: Graph File

Thread ID: 21277412

  %total   %self     total      self    children               calls   Name
-/____________________________________________________________________________/
-100.00%   0.00%      8.77      0.00      8.77                   1     #toplevel*
-                     8.77      0.00      8.77                 1/1     Object#run_primes
-/____________________________________________________________________________/
-                     8.77      0.00      8.77                 1/1     #toplevel
-100.00%   0.00%      8.77      0.00      8.77                   1     Object#run_primes*
-                     0.02      0.00      0.02                 1/1     Object#make_random_array
-                     2.09      0.00      2.09                 1/1     Object#find_largest
-                     6.66      0.00      6.66                 1/1     Object#find_primes
-/____________________________________________________________________________/
-                     0.02      0.02      0.00                 1/1     Object#make_random_array
-0.18%     0.18%      0.02      0.02      0.00                   1     Array#each_index
-                     0.00      0.00      0.00             500/500     Kernel.rand
-                     0.00      0.00      0.00             500/501     Array#[]=
-/____________________________________________________________________________/

As you can see the calls have been separated into slices, no longer is the order determined by process time but instead from hierarchy. Each slice profiles a primary entry, with the primary entry's parents being shown above itself and it's children found below. A primary entry can be ascertained by it having values in the %total and %self columns. Here the main entry here have been bolded for connivence.

So if we look at the last slice. The primary entry would be Array#each_index. It takes 0.18% of the total process time and it is only called once. It is called from Object#make_random_array which is only called once. It's children are Kernal.rand which is called by it all 500 its times that it was call in this action and Arry#[]= which was called 500 times by Array#each_index and once by some other entry.

5.4. Tree Files

It's pointless trying to represent a tree file textually so here's a few pretty pictures of it's usefulness

KCachegrind Graph

- Graph created by KCachegrind -

KCachegrind List

- List created by KCachegrind -

#TODO Add a bit more information to this.

6. Getting to the Point of all of this

Now I know all of this is a bit dry and academic. But it's a very powerful tool when you know how to leverage it properly. Which we are going to take a look at in our next section

7. Real Life Example

7.1. The setup

So I have been building this application for the last month and feel pretty good about the ruby code. I'm readying it for beta testers when I discover to my shock that with less then twenty people it starts to crash. It's a pretty simple Ecommerce site so I'm very confused by what I'm seeing. On running looking through my log files I find to my shock that the lowest time for a page run is running around 240 ms. My database finds aren't the problems so I'm lost as to what is happening to cause all this. Lets run a benchmark.

class HomepageTest < ActionController::PerformanceTest
-  # Replace this with your real tests.
-  def test_homepage
-    get '/'
-  end
-end
-

Example: Output

HomepageTest#test_homepage (115 ms warmup)
-        process_time: 591 ms
-        memory: 3052.90 KB
-        objects: 59471

Obviously something is very very wrong here. 3052.90 Kb to load my minimal homepage. For Comparison for another site running well I get this for my homepage test.

Example: Default

HomepageTest#test_homepage (19 ms warmup)
-        process_time: 26 ms
-              memory: 298.79 KB
-             objects: 1917

that over a factor of ten difference. Lets look at our flat process time file to see if anything pops out at us.

Example: Process time

20.73      0.39     0.12     0.00     0.27      420  Pathname#cleanpath_aggressive
-17.07      0.14     0.10     0.00     0.04     3186  Pathname#chop_basename
- 6.47      0.06     0.04     0.00     0.02     6571  Kernel#===
- 5.04      0.06     0.03     0.00     0.03      840  Pathname#initialize
- 5.03      0.05     0.03     0.00     0.02        4  ERB::Compiler::ExplicitScanner#scan
- 4.51      0.03     0.03     0.00     0.00     9504  String#==
- 2.94      0.46     0.02     0.00     0.44     1393  String#gsub
- 2.66      0.09     0.02     0.00     0.07      480  Array#each
- 2.46      0.01     0.01     0.00     0.00     3606  Regexp#to_s

Yes indeed we seem to have found the problem. Pathname#cleanpath_aggressive is taking nearly a quarter our process time and Pathname#chop_basename another 17%. From here I do a few more benchmarks to make sure that these processes are slowing down the other pages. They are so now I know what I must do. If we can get rid of or shorten these processes we can make our pages run much quicker.

Now both of these are main ruby processes so are goal right now is to find out what other process is calling them. Glancing at our Graph file I see that #cleanpath is calling #cleanpath_aggressive. #cleanpath is being called by String#gsub and from there some html template errors. But my page seems to be rendering fine. why would it be calling template errors. I'm decide to check my object flat file to see if I can find any more information.

Example: Objects Created

20.74  34800.00 12324.00     0.00 22476.00      420  Pathname#cleanpath_aggressive
-16.79  18696.00  9978.00     0.00  8718.00     3186  Pathname#chop_basename
-11.47  13197.00  6813.00     0.00  6384.00      480  Array#each
- 8.51  41964.00  5059.00     0.00 36905.00     1386  String#gsub
- 6.07   3606.00  3606.00     0.00     0.00     3606  Regexp#to_s

nope nothing new here. Lets look at memory usage

Example: Memory Consuption

 40.17   1706.80  1223.70     0.00   483.10     3186  Pathname#chop_basename
- 14.92    454.47   454.47     0.00     0.00     3606  Regexp#to_s
-  7.09   2381.36   215.99     0.00  2165.37     1386  String#gsub
-  5.08    231.19   154.73     0.00    76.46      420  Pathname#prepend_prefix
-  2.34     71.35    71.35     0.00     0.00     1265  String#initialize_copy

Ok so it seems Regexp#to_s is the second costliest process. At this point I try to figure out what could be calling a regular expression cause I very rarely use them. Going over my standard layout I discover at the top.

<%if request.env["HTTP_USER_AGENT"].match(/Opera/)%>
-<%= stylesheet_link_tag "opera" %>
-<% end %>
-

That's wrong. I mistakenly am using a search function for a simple compare function. Lets fix that.

<%if request.env["HTTP_USER_AGENT"] =~ /Opera/%>
-<%= stylesheet_link_tag "opera" %>
-<% end %>
-

I'll now try my test again.

process_time: 75 ms
-              memory: 519.95 KB
-             objects: 6537

Much better. The problem has been solved. Now I should have realized earlier due to the String#gsub that my problem had to be with reqexp serch function but such knowledge comes with time. Looking through the mass output data is a skill.

8. Get Yourself a Game Plan

You end up dealing with a large amount of data whenever you profile an application. It's crucial to use a rigorous approach to analyzing your application's performance else fail miserably in a vortex of numbers. This leads us to -

8.1. The Analysis Process

I’m going to give an example methodology for conducting your benchmarking and profiling on an application. It is based on your typical scientific method.

For something as complex as Benchmarking you need to take any methodology with a grain of salt but there are some basic strictures that you can depend on.

Formulate a question you need to answer which is simple, tests the smallest measurable thing possible, and is exact. This is typically the hardest part of the experiment. From there some steps that you should follow are.

-
-Develop a set of variables and processes to measure in order to answer this question! -
-
-
-Profile based on the question and variables. Key problems to avoid when designing this experiment are: -
-
- -
  -Confounding: Test one thing at a time, keep everything the same so you don't poison the data with uncontrolled processes. -
  -
- -
  -Cross Contamination: Make sure that runs from one test do not harm the other tests. -
  -
- -
  -Steady States: If you’re testing long running process. You must take the ramp up time and performance hit into your initial measurements. -
  -
- -
  -Sampling Error: Data should perform have a steady variance or range. If you get wild swings or sudden spikes, etc. then you must either account for the reason why or you have a sampling error. -
  -
- -
  -Measurement Error: Aka Human error, always go through your calculations at least twice to make sure there are no mathematical errors. . -
  -
-
-
-Do a small run of the experiment to verify the design. -
-
-
-Use the small run to determine a proper sample size. -
-
-
-Run the test. -
-
-
-Perform the analysis on the results and determine where to go from there. -
-

Note: Even though we are using the typical scientific method; developing a hypothesis is not always useful in terms of profiling.

9. Other Profiling Tools

There are a lot of great profiling tools out there. Some free, some not so free. This is a sort list detailing some of them.

9.1. httperf

http://www.hpl.hp.com/research/linux/httperf/

A necessary tool in your arsenal. Very useful for load testing your website.

#TODO write and link to a short article on how to use httperf. Anybody have a good tutorial availble.

9.2. Rails Analyzer

The Rails Analyzer project contains a collection of tools for Rails. It's open source and pretty speedy. It's not being actively worked on but is still contains some very useful tools.

-
-The Production Log Analyzer examines Rails log files and gives back a report. It also includes action_grep which will give you all log results for a particular action. -
-
-
-The Action Profiler similar to Ruby-Prof profiler. -
-
-
-rails_stat which gives a live counter of requests per second of a running Rails app. -
-
-
-The SQL Dependency Grapher allows you to visualize the frequency of table dependencies in a Rails application. -
-

Their project homepage can be found at http://rails-analyzer.rubyforge.org/

The one major caveat is that it needs your log to be in a different format from how rails sets it up specifically SyslogLogger.

9.2.1. SyslogLogger

SyslogLogger is a Logger work-alike that logs via syslog instead of to a file. You can add SyslogLogger to your Rails production environment to aggregate logs between multiple machines.

More information can be found out at http://rails-analyzer.rubyforge.org/hacks/classes/SyslogLogger.html

If you don't have access to your machines root system or just want something a bit easier to implement there is also a module developed by Geoffrey Grosenbach

9.2.2. A Hodel 3000 Compliant Logger for the Rest of Us

Directions taken from -link to module file

Just put the module in your lib directory and add this to your environment.rb in it's config portion.

require 'hodel_3000_compliant_logger'
-config.logger = Hodel3000CompliantLogger.new(config.log_path)

It's that simple. Your log output on restart should look like this.

Example: Hodel 3000 Example

Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]:
-Parameters: {"action"=>"shipping", "controller"=>"checkout"}
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]: 
-[4;36;1mBook Columns (0.003155)[0m   [0;1mSHOW FIELDS FROM `books`[0m
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]: 
-[4;35;1mBook Load (0.000881)[0m   [0mSELECT * FROM `books` WHERE (`books`.`id` = 1 AND (`books`.`sold` = 1)) [0m
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]: 
-[4;36;1mShippingAddress Columns (0.002683)[0m   [0;1mSHOW FIELDS FROM `shipping_addresses`[0m
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]: 
-[4;35;1mBook Load (0.000362)[0m   [0mSELECT ounces FROM `books` WHERE (`books`.`id` = 1) [0m
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]:
-Rendering template within layouts/application
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]:
-Rendering checkout/shipping
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]: 
-[4;36;1mBook Load (0.000548)[0m   [0;1mSELECT * FROM `books`
-WHERE (sold = 0) LIMIT 3[0m
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]: 
-[4;35;1mAuthor Columns (0.002571)[0m   [0mSHOW FIELDS FROM `authors`[0m
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]:
-[4;36;1mAuthor Load (0.000811)[0m   [0;1mSELECT * FROM `authors` WHERE (`authors`.`id` = 1) [0m
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]:
-Rendered store/_new_books (0.01358)
-Jul 15 11:45:43 matthew-bergmans-macbook-pro-15 rails[16207]:
-Completed in 0.37297 (2 reqs/sec) | Rendering: 0.02971 (7%) | DB: 0.01697 (4%) | 200 OK [https://secure.jeffbooks/checkout/shipping]

9.3. Palmist

An open source mysql query analyzer. Full featured and easy to work with. Also requires Hodel 3000 -http://www.flyingmachinestudios.com/projects/

9.4. New Relic

http://www.newrelic.com/

Pretty nifty performance tools, pricey though. They do have a basic free -service both for when in development and when you put your application into production. Very simple installation and signup.

#TODO more in-depth without being like an advertisement.

9.4.1. Manage

Like new relic a production monitoring tool.

10. Changelog

Lighthouse ticket

-
-October 17, 2008: First revision by Pratik -
-
-
-September 6, 2008: Initial version by Matthew Bergman <MzbPhoto@gmail.com> -
-

- -

- - diff --git a/railties/doc/guides/html/caching_with_rails.html b/railties/doc/guides/html/caching_with_rails.html index 32a98d1314..02cc981b0e 100644 --- a/railties/doc/guides/html/caching_with_rails.html +++ b/railties/doc/guides/html/caching_with_rails.html @@ -1,244 +1,76 @@ - - Caching with Rails: An overview - - - - - + + Caching with Rails: An overview + + + + - - -

- - - -

Caching with Rails: An overview

+ + +

+ + + +

Caching with Rails: An overview

Everyone caches. This guide will teach you what you need to know about +

Everyone caches. This guide will teach you what you need to know about avoiding that expensive round-trip to your database and returning what you need to return to those hungry web clients in the shortest time possible.

1. Basic Caching

This is an introduction to the three types of caching techniques that Rails +

This is an introduction to the three types of caching techniques that Rails provides by default without the use of any third party plugins.

To get started make sure config.action_controller.perform_caching is set +

To get started make sure config.action_controller.perform_caching is set to true for your environment. This flag is normally set in the corresponding config/environments/*.rb and caching is disabled by default there for development and test, and enabled for production.

@@ -247,16 +79,15 @@ there for development and test, and enabled for production.

by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -

config.action_controller.perform_caching = true
-

config.action_controller.perform_caching = true

1.1. Page Caching

Page caching is a Rails mechanism which allows the request for a generated +

Page caching is a Rails mechanism which allows the request for a generated page to be fulfilled by the webserver, without ever having to go through the -Rails stack at all. Obviously, this is super-fast. Unfortunately, it can't be +Rails stack at all. Obviously, this is super-fast. Unfortunately, it can’t be applied to every situation (such as pages that need authentication) and since the webserver is literally just serving a file from the filesystem, cache expiration is an issue that needs to be dealt with.

So, how do you enable this super-fast cache behavior? Simple, let's say you +

So, how do you enable this super-fast cache behavior? Simple, let’s say you have a controller called ProductsController and a list action that lists all the products

@@ -270,23 +101,22 @@ http://www.gnu.org/software/src-highlite --> def index; end -end -

The first time anyone requests products/index, Rails will generate a file +end

The first time anyone requests products/index, Rails will generate a file called index.html and the webserver will then look for that file before it passes the next request for products/index to your Rails application.

By default, the page cache directory is set to Rails.public_path (which is +

By default, the page cache directory is set to Rails.public_path (which is usually set to RAILS_ROOT + "/public") and this can be configured by changing the configuration setting config.action_controller.page_cache_directory. Changing the default from /public helps avoid naming conflicts, since you may want to put other static html in /public, but changing this will require web server reconfiguration to let the web server know where to serve the cached files from.

The Page Caching mechanism will automatically add a .html exxtension to +

The Page Caching mechanism will automatically add a .html exxtension to requests for pages that do not have an extension to make it easy for the webserver to find those pages and this can be configured by changing the configuration setting config.action_controller.page_cache_extension.

In order to expire this page when a new product is added we could extend our +

In order to expire this page when a new product is added we could extend our example controler like this:

expire_page :action => :list end -end -

If you want a more complicated expiration scheme, you can use cache sweepers +end

If you want a more complicated expiration scheme, you can use cache sweepers to expire cached objects when things change. This is covered in the section on Sweepers.

1.2. Action Caching

One of the issues with Page Caching is that you cannot use it for pages that +

One of the issues with Page Caching is that you cannot use it for pages that require to restrict access somehow. This is where Action Caching comes in. Action Caching works like Page Caching except for the fact that the incoming web request does go from the webserver to the Rails stack and Action Pack so that before filters can be run on it before the cache is served, so that authentication and other restrictions can be used while still serving the result of the output from a cached copy.

Clearing the cache works in the exact same way as with Page Caching.

Let's say you only wanted authenticated users to edit or create a Product +

Clearing the cache works in the exact same way as with Page Caching.

Let’s say you only wanted authenticated users to edit or create a Product object, but still cache those pages:

def edit; end -end -

And you can also use :if (or :unless) to pass a Proc that specifies when the -action should be cached. Also, you can use :layout ⇒ false to cache without +end

And you can also use :if (or :unless) to pass a Proc that specifies when the +action should be cached. Also, you can use :layout => false to cache without layout so that dynamic information in the layout such as logged in user info or the number of items in the cart can be left uncached. This feature is available as of Rails 2.2.

[More: more examples? Walk-through of Action Caching from request to response? +

[More: more examples? Walk-through of Action Caching from request to response? Description of Rake tasks to clear cached files? Show example of subdomain caching? Talk about :cache_path, :if and assing blocks/Procs to expire_action?]

1.3. Fragment Caching

Life would be perfect if we could get away with caching the entire contents of +

Life would be perfect if we could get away with caching the entire contents of a page or action and serving it out to the world. Unfortunately, dynamic web applications usually build pages with a variety of components not all of which have the same caching characteristics. In order to address such a dynamically created page where different parts of the page need to be cached and expired differently Rails provides a mechanism called Fragment Caching.

Fragment Caching allows a fragment of view logic to be wrapped in a cache +

Fragment Caching allows a fragment of view logic to be wrapped in a cache block and served out of the cache store when the next request comes in.

As an example, if you wanted to show all the orders placed on your website -in real time and didn't want to cache that part of the page, but did want +

As an example, if you wanted to show all the orders placed on your website +in real time and didn’t want to cache that part of the page, but did want to cache the part of the page which lists all products available, you could use this piece of code:

@@ -376,9 +204,8 @@ http://www.gnu.org/software/src-highlite --> <% Product.find(:all).each do |p| %> <%= link_to p.name, product_url(p) %> <% end %> -<% end %> -

The cache block in our example will bind to the action that called it and is +<% end %>

The cache block in our example will bind to the action that called it and is written out to the same place as the Action Cache, which means that if you want to cache multiple fragments per action, you should provide an action_suffix to the cache call:

@@ -387,17 +214,15 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->

<% cache(:action => 'recent', :action_suffix => 'all_products') do %>
-  All available products:
-

and you can expire it using the expire_fragment method, like so:

+ All available products:

and you can expire it using the expire_fragment method, like so:

expire_fragment(:controller => 'products', :action => 'recent', :action_suffix => 'all_products)
-

If you don't want the cache block to bind to the action that called it, You can +

expire_fragment(:controller => 'products', :action => 'recent', :action_suffix => 'all_products)

If you don’t want the cache block to bind to the action that called it, You can also use globally keyed fragments by calling the cache method with a key, like so:

@@ -406,25 +231,23 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->

<% cache(:key => ['all_available_products', @latest_product.created_at].join(':')) do %>
-  All available products:
-

This fragment is then available to all actions in the ProductsController using + All available products:

This fragment is then available to all actions in the ProductsController using the key and can be expired the same way:

expire_fragment(:key => ['all_available_products', @latest_product.created_at].join(':'))
-

expire_fragment(:key => ['all_available_products', @latest_product.created_at].join(':'))

1.4. Sweepers

Cache sweeping is a mechanism which allows you to get around having a ton of +

Cache sweeping is a mechanism which allows you to get around having a ton of expire_{page,action,fragment} calls in your code by moving all the work required to expire cached content into a ActionController::Caching::Sweeper class that is an Observer and looks for changes to an object via callbacks, and when a change occurs it expires the caches associated with that object n an around or after filter.

Continuing with our Product controller example, we could rewrite it with a +

Continuing with our Product controller example, we could rewrite it with a sweeper such as the following:

class StoreSweeper < ActionController::Caching::Sweeper
-  observe Product # This sweeper is going to keep an eye on the Post model
+  observe Product # This sweeper is going to keep an eye on the Product model
 
-  # If our sweeper detects that a Post was created call this
+  # If our sweeper detects that a Product was created call this
   def after_create(product)
           expire_cache_for(product)
   end
 
-  # If our sweeper detects that a Post was updated call this
+  # If our sweeper detects that a Product was updated call this
   def after_update(product)
           expire_cache_for(product)
   end
 
-  # If our sweeper detects that a Post was deleted call this
+  # If our sweeper detects that a Product was deleted call this
   def after_destroy(product)
           expire_cache_for(product)
   end
@@ -457,9 +280,8 @@ http://www.gnu.org/software/src-highlite -->
     # Expire a fragment
     expire_fragment(:controller => '#{record}', :action => 'recent', :action_suffix => 'all_products')
   end
-end
-

Then we add it to our controller to tell it to call the sweeper when certain +end

Then we add it to our controller to tell it to call the sweeper when certain actions are called. So, if we wanted to expire the cached content for the list and edit actions when the create action was called, we could do the following:

@@ -484,14 +306,13 @@ http://www.gnu.org/software/src-highlite --> def edit; end -end -

+end

1.5. SQL Caching

Query caching is a Rails feature that caches the result set returned by each +

Query caching is a Rails feature that caches the result set returned by each query so that if Rails encounters the same query again for that request, it will used the cached result set as opposed to running the query against the database again.

For example:

def edit; end -end -

In the list action above, the result set returned by the first +end

In the list action above, the result set returned by the first Product.find(:all) will be cached and will be used to avoid querying the database again the second time that finder is called.

Query caches are created at the start of an action and destroyed at the end of +

Query caches are created at the start of an action and destroyed at the end of that action and thus persist only for the duration of the action.

1.6. Cache stores

Rails provides different stores for the cached data for action and fragment +

Rails provides different stores for the cached data for action and fragment caches. Page caches are always stored on disk.

The cache stores provided include:

1) Memory store: Cached data is stored in the memory allocated to the Rails +

The cache stores provided include:

1) Memory store: Cached data is stored in the memory allocated to the Rails process, which is fine for WEBrick and for FCGI (if you - don't care that each FCGI process holds its own fragment - store). It's not suitable for CGI as the process is thrown + don’t care that each FCGI process holds its own fragment + store). It’s not suitable for CGI as the process is thrown away at the end of each request. It can potentially also take up a lot of memory since each process keeps all the caches in memory.

@@ -544,9 +364,8 @@ caches. Page caches are always stored on disk.

by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -

ActionController::Base.cache_store = :memory_store
-

2) File store: Cached data is stored on the disk, this is the default store +

ActionController::Base.cache_store = :memory_store

2) File store: Cached data is stored on the disk, this is the default store and the default path for this store is: /tmp/cache. Works well for all types of environments and allows all processes running from the same application directory to access the @@ -556,9 +375,8 @@ http://www.gnu.org/software/src-highlite --> by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -

ActionController::Base.cache_store = :file_store, "/path/to/cache/directory"
-

3) DRb store: Cached data is stored in a separate shared DRb process that all +

ActionController::Base.cache_store = :file_store, "/path/to/cache/directory"

3) DRb store: Cached data is stored in a separate shared DRb process that all servers communicate with. This works for all environments and only keeps one cache around for all processes, but requires that you run and manage a separate DRb process.

@@ -567,41 +385,38 @@ http://www.gnu.org/software/src-highlite --> by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -

ActionController::Base.cache_store = :drb_store, "druby://localhost:9192"
-

4) MemCached store: Works like DRbStore, but uses Danga's MemCache instead. +

ActionController::Base.cache_store = :drb_store, "druby://localhost:9192"

4) MemCached store: Works like DRbStore, but uses Danga’s MemCache instead. Rails uses the bundled memcached-client gem by default.

ActionController::Base.cache_store = :mem_cache_store, "localhost"
-

5) Custom store: You can define your own cache store (new in Rails 2.1)

ActionController::Base.cache_store = :mem_cache_store, "localhost"

5) Custom store: You can define your own cache store (new in Rails 2.1)

ActionController::Base.cache_store = MyOwnStore.new("parameter")
-

Note: config.cache_store can be used in place of +

ActionController::Base.cache_store = MyOwnStore.new("parameter")

+Note: config.cache_store can be used in place of ActionController::Base.cache_store in your Rails::Initializer.run block in environment.rb 2. Conditional GET support

-

Conditional GETs are a facility of the HTTP spec that provide a way for web + Conditional GETs are a facility of the HTTP spec that provide a way for web servers to tell browsers that the response to a GET request hasn’t changed since the last request and can be safely pulled from the browser cache. -

They work by using the HTTP_IF_NONE_MATCH and HTTP_IF_MODIFIED_SINCE headers to + They work by using the HTTP_IF_NONE_MATCH and HTTP_IF_MODIFIED_SINCE headers to pass back and forth both a unique content identifier and the timestamp of when the content was last changed. If the browser makes a request where the content identifier (etag) or last modified since timestamp matches the server’s version then the server only needs to send back an empty response with a not modified status. -

It is the server’s (i.e. our) responsibility to look for a last modified + It is the server’s (i.e. our) responsibility to look for a last modified timestamp and the if-none-match header and determine whether or not to send back the full response. With conditional-get support in rails this is a pretty easy task: @@ -627,9 +442,8 @@ http://www.gnu.org/software/src-highlite --> # anything. The default render checks for this using the parameters # used in the previous call to stale? and will automatically send a # :not_modified. So that's it, you're done. -end -

If you don’t have any special response processing and are using the default +end

If you don’t have any special response processing and are using the default rendering mechanism (i.e. you’re not using respond_to or calling render yourself) then you’ve got an easy helper in fresh_when:

@@ -646,22 +460,21 @@ http://www.gnu.org/software/src-highlite --> @product = Product.find(params[:id]) fresh_when :last_modified => @product.published_at.utc, :etag => @article end -end -

+end

3. Advanced Caching

Along with the built-in mechanisms outlined above, a number of excellent +

Along with the built-in mechanisms outlined above, a number of excellent plugins exist to help with finer grained control over caching. These include -Chris Wanstrath's excellent cache_fu plugin (more info here: -http://errtheblog.com/posts/57-kickin-ass-w-cachefu) and Evan Weaver's +Chris Wanstrath’s excellent cache_fu plugin (more info here: +http://errtheblog.com/posts/57-kickin-ass-w-cachefu) and Evan Weaver’s interlock plugin (more info here: http://blog.evanweaver.com/articles/2007/12/13/better-rails-caching/). Both of these plugins play nice with memcached and are a must-see for anyone seriously considering optimizing their caching needs.

- + + diff --git a/railties/doc/guides/html/command_line.html b/railties/doc/guides/html/command_line.html index 2a28da177e..226a68e105 100644 --- a/railties/doc/guides/html/command_line.html +++ b/railties/doc/guides/html/command_line.html @@ -1,224 +1,68 @@ - - A Guide to The Rails Command Line - - - - - + + A Guide to The Rails Command Line + + + + - - -

- - - -

A Guide to The Rails Command Line

+ + +

+ + + +

A Guide to The Rails Command Line

Rails comes with every command line tool you'll need to

Rails comes with every command line tool you’ll need to

Create a Rails application @@ -245,14 +89,14 @@ Profile and benchmark your new creation

… and much, much more! (Buy now!)

This tutorial assumes you have basic Rails knowledge from reading the Getting Started with Rails Guide.

... and much, much more! (Buy now!)

This tutorial assumes you have basic Rails knowledge from reading the Getting Started with Rails Guide.

1. Command Line Basics

There are a few commands that are absolutely critical to your everyday usage of Rails. In the order of how much you'll probably use them are:

There are a few commands that are absolutely critical to your everyday usage of Rails. In the order of how much you’ll probably use them are:

console @@ -279,9 +123,9 @@ rails

Let's create a simple Rails application to step through each of these commands in context.

Let’s create a simple Rails application to step through each of these commands in context.

1.1. rails

The first thing we'll want to do is create a new Rails application by running the rails command after installing Rails.

The first thing we’ll want to do is create a new Rails application by running the rails command after installing Rails.

Editor’s note:

If you haven’t set up the custom route from above, script/destroy will fail and you’ll have to remove it manually.

@@ -305,9 +149,8 @@ http://www.gnu.org/software/src-highlite --> ... create log/production.log create log/development.log - create log/test.log - -

Rails will set you up with what seems like a huge amount of stuff for such a tiny command! You've got the entire Rails directory structure now with all the code you need to run our simple application right out of the box.

+ create log/test.log +

Rails will set you up with what seems like a huge amount of stuff for such a tiny command! You’ve got the entire Rails directory structure now with all the code you need to run our simple application right out of the box.

@@ -317,16 +160,16 @@ http://www.gnu.org/software/src-highlite -->

1.2. server

Let's try it! The server command launches a small web server written in Ruby named WEBrick which was also installed when you installed Rails. You'll use this any time you want to view your work through a web browser.

Let’s try it! The server command launches a small web server named WEBrick which comes bundled with Ruby. You’ll use this any time you want to view your work through a web browser.

- +

WEBrick isn't your only option for serving Rails. We'll get to that in a later section. [XXX: which section]

WEBrick isn’t your only option for serving Rails. We’ll get to that in a later section. [XXX: which section]

Here we'll flex our server command, which without any prodding of any kind will run our new shiny Rails app:

Here we’ll flex our server command, which without any prodding of any kind will run our new shiny Rails app:

create app/controllers/greetings_controller.rb create test/functional/greetings_controller_test.rb create app/helpers/greetings_helper.rb - create app/views/greetings/hello.html.erb -

Look there! Now what all did this generate? It looks like it made sure a bunch of directories were in our application, and created a controller file, a functional test file, a helper for the view, and a view file.

Let's check out the controller and modify it a little (in app/controllers/greeting_controller.rb):

+ create app/views/greetings/hello.html.erb +

Let’s check out the controller and modify it a little (in app/controllers/greeting_controller.rb):

@message = "Hello, how are you today? I am exuberant!" end -end -

Then the view, to display our nice message (in app/views/greeting/hello.html.erb):

+end +

Then the view, to display our nice message (in app/views/greeting/hello.html.erb):

<h1>A Greeting for You!</h1>
-<p><%= @message %></p>
-

Deal. Go check it out in your browser. Fire up your server. Remember? ./script/server at the root of your Rails application should do it.

+<p><%= @message %></p> +

Deal. Go check it out in your browser. Fire up your server. Remember? ./script/server at the root of your Rails application should do it.

$ ./script/server
-=> Booting WEBrick...
-

The URL will be http://localhost:3000/greetings/hello. I'll wait for you to be suitably impressed.

+=> Booting WEBrick... +

The URL will be http://localhost:3000/greetings/hello. I’ll wait for you to be suitably impressed.

@@ -466,7 +302,7 @@ http://www.gnu.org/software/src-highlite -->

With a normal, plain-old Rails application, your URLs will generally follow the pattern of http://(host)/(controller)/(action), and a URL like http://(host)/(controller) will hit the index action of that controller.

"What about data, though?", you ask over a cup of coffee. Rails comes with a generator for data models too. Can you guess its generator name?

$ ./script/generate model HighScore id:integer game:string score:integer
-      exists  app/models/
-      exists  test/unit/
-      exists  test/fixtures/
-      create  app/models/high_score.rb
-      create  test/unit/high_score_test.rb
-      create  test/fixtures/high_scores.yml
-      create  db/migrate
-      create  db/migrate/20081126032945_create_high_scores.rb
-

Taking it from the top, we have the models directory, where all of your data models live. test/unit, where all the unit tests live (gasp! — unit tests!), fixtures for those tests, a test, the migrate directory, where the database-modifying migrations live, and a migration to create the high_scores table with the right fields.

The migration requires that we migrate, that is, run some Ruby code (living in that 20081126032945_create_high_scores.rb) to modify the schema of our database. Which database? The sqlite3 database that Rails will create for you when we run the rake db:migrate command. We'll talk more about Rake in-depth in a little while.

$ ./script/generate scaffold HighScore game:string score:integer
+    exists  app/models/
+    exists  app/controllers/
+    exists  app/helpers/
+    create  app/views/high_scores
+    create  app/views/layouts/
+    exists  test/functional/
+    create  test/unit/
+    create  public/stylesheets/
+    create  app/views/high_scores/index.html.erb
+    create  app/views/high_scores/show.html.erb
+    create  app/views/high_scores/new.html.erb
+    create  app/views/high_scores/edit.html.erb
+    create  app/views/layouts/high_scores.html.erb
+    create  public/stylesheets/scaffold.css
+    create  app/controllers/high_scores_controller.rb
+    create  test/functional/high_scores_controller_test.rb
+    create  app/helpers/high_scores_helper.rb
+     route  map.resources :high_scores
+dependency  model
+    exists    app/models/
+    exists    test/unit/
+    create    test/fixtures/
+    create    app/models/high_score.rb
+    create    test/unit/high_score_test.rb
+    create    test/fixtures/high_scores.yml
+    exists    db/migrate
+    create    db/migrate/20081217071914_create_high_scores.rb

Taking it from the top - the generator checks that there exist the directories for models, controllers, helpers, layouts, functional and unit tests, stylesheets, creates the views, controller, model and database migration for HighScore (creating the high_scores table and fields), takes care of the route for the resource, and new tests for everything.

The migration requires that we migrate, that is, run some Ruby code (living in that 20081217071914_create_high_scores.rb) to modify the schema of our database. Which database? The sqlite3 database that Rails will create for you when we run the rake db:migrate command. We’ll talk more about Rake in-depth in a little while.

+ + + +

+ +	Hey. Install the sqlite3-ruby gem while you’re at it. `gem install sqlite3-ruby`

== CreateHighScores: migrating =============================================== -- create_table(:high_scores) -> 0.0070s -== CreateHighScores: migrated (0.0077s) ====================================== -

+== CreateHighScores: migrated (0.0077s) ======================================

- +

Let's talk about unit tests. Unit tests are code that tests and makes assertions about code. In unit testing, we take a little part of code, say a method of a model, and test its inputs and outputs. Unit tests are your friend. The sooner you make peace with the fact that your quality of life will drastically increase when you unit test your code, the better. Seriously. We'll make one in a moment.

Let’s talk about unit tests. Unit tests are code that tests and makes assertions about code. In unit testing, we take a little part of code, say a method of a model, and test its inputs and outputs. Unit tests are your friend. The sooner you make peace with the fact that your quality of life will drastically increase when you unit test your code, the better. Seriously. We’ll make one in a moment.

Yo! Let's shove a small table into our greeting controller and view, listing our sweet scores.

Let’s see the interface Rails created for us. ./script/server; http://localhost:3000/high_scores

We can create new high scores (55,160 on Space Invaders!)

1.4. console

The console command lets you interact with your Rails application from the command line. On the underside, script/console uses IRB, so if you’ve ever used it, you’ll be right at home. This is useful for testing out quick ideas with code and changing data server-side without touching the website.

1.5. dbconsole

dbconsole figures out which database you’re using and drops you into whichever command line interface you would use with it (and figures out the command line parameters to give to it, too!). It supports MySQL, PostgreSQL, SQLite and SQLite3.

1.6. plugin

The plugin command simplifies plugin management; think a miniature version of the Gem utility. Let’s walk through installing a plugin. You can call the sub-command discover, which sifts through repositories looking for plugins, or call source to add a specific repository of plugins, or you can specify the plugin location directly.

Let’s say you’re creating a website for a client who wants a small accounting system. Every event having to do with money must be logged, and must never be deleted. Wouldn’t it be great if we could override the behavior of a model to never actually take its record out of the database, but instead, just set a field?

There is such a thing! The plugin we’re installing is called "acts_as_paranoid", and it lets models implement a "deleted_at" column that gets set when you call destroy. Later, when calling find, the plugin will tack on a database check to filter out "deleted" things.

class GreetingController < ApplicationController
-  def hello
-    if request.post?
-      score = HighScore.new(params[:high_score])
-      if score.save
-        flash[:notice] = "New score posted!"
-      end
-    end
-
-    @scores = HighScore.find(:all)
-  end
-
-end
-

XXX: Go with scaffolding instead, modifying greeting controller for high scores seems dumb.

$ ./script/plugin install http://svn.techno-weenie.net/projects/plugins/acts_as_paranoid
++ ./CHANGELOG
++ ./MIT-LICENSE
+...
+...

1.7. runner

runner runs Ruby code in the context of Rails non-interactively. For instance:

$ ./script/runner "Model.long_running_method"

1.8. destroy

Think of destroy as the opposite of generate. It’ll figure out what generate did, and undo it. Believe you-me, the creation of this tutorial used this command many times!

$ ./script/generate model Oops
+      exists  app/models/
+      exists  test/unit/
+      exists  test/fixtures/
+      create  app/models/oops.rb
+      create  test/unit/oops_test.rb
+      create  test/fixtures/oops.yml
+      exists  db/migrate
+      create  db/migrate/20081221040817_create_oops.rb
+$ ./script/destroy model Oops
+    notempty  db/migrate
+    notempty  db
+          rm  db/migrate/20081221040817_create_oops.rb
+          rm  test/fixtures/oops.yml
+          rm  test/unit/oops_test.rb
+          rm  app/models/oops.rb
+    notempty  test/fixtures
+    notempty  test
+    notempty  test/unit
+    notempty  test
+    notempty  app/models
+    notempty  app

1.9. about

Check it: Version numbers for Ruby, RubyGems, Rails, the Rails subcomponents, your application’s folder, the current Rails environment name, your app’s database adapter, and schema version! about is useful when you need to ask help, check if a security patch might affect you, or when you need some stats for an existing Rails installation.

$ ./script/about
+About your application's environment
+Ruby version              1.8.6 (i486-linux)
+RubyGems version          1.3.1
+Rails version             2.2.0
+Active Record version     2.2.0
+Action Pack version       2.2.0
+Active Resource version   2.2.0
+Action Mailer version     2.2.0
+Active Support version    2.2.0
+Edge Rails revision       unknown
+Application root          /home/commandsapp
+Environment               development
+Database adapter          sqlite3
+Database schema version   20081217073400

- - + + diff --git a/railties/doc/guides/html/configuring.html b/railties/doc/guides/html/configuring.html index adc827c89a..3cd41f100e 100644 --- a/railties/doc/guides/html/configuring.html +++ b/railties/doc/guides/html/configuring.html @@ -1,253 +1,82 @@ - - Configuring Rails Applications - - - - - + + Configuring Rails Applications + + + + - - -

- - - -

Configuring Rails Applications

+ + +

+ + + +

Configuring Rails Applications

This guide covers the configuration and initialization features available to Rails applications. By referring to this guide, you will be able to:

Adjust the behavior of your Rails applications @@ -259,29 +88,73 @@ Add additional code to be run at application start time

+ + + +

+ +	The first edition of this Guide was written from the Rails 2.3 source code. While the information it contains is broadly applicable to Rails 2.2, backwards compatibility is not guaranteed.

1. Locations for Initialization Code

preinitializers -environment.rb first -env-specific files -initializers (load_application_initializers) -after-initializer

Rails offers (at least) five good spots to place initialization code:

+
+Preinitializers +
+
+
+environment.rb +
+
+
+Environment-specific Configuration Files +
+
+
+Initializers (load_application_initializers) +
+
+
+After-Initializers +
+

2. Using a Preinitializer

Rails allows you to use a preinitializer to run code before the framework itself is loaded. If you save code in RAILS_ROOT/config/preinitializer.rb, that code will be the first thing loaded, before any of the framework components (Active Record, Action Pack, and so on.) If you want to change the behavior of one of the classes that is used in the initialization process, you can do so in this file.

3. Initialization Process Settings

4. Configuring Rails Components

3. Configuring Rails Components

4.1. Configuring Active Record

ActiveRecord::Base includej a variety of configuration options:

logger accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed on to any new database connections made. You can retrieve this logger by calling logger on either an ActiveRecord model class or an ActiveRecord model instance. Set to nil to disable logging.

primary_key_prefix_type lets you adjust the naming for primary key columns. By default, Rails assumes that primary key columns are named id (and this configuration option doesn't need to be set.) There are two other choices:

In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The environment.rb and environment-specific configuration files (such as config/environments/production.rb) allow you to specify the various settings that you want to pass down to all of the components. For example, the default Rails 2.3 environment.rb file includes one setting:

config.time_zone = 'UTC'

This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same config object:

config.active_record.colorize_logging = false

Rails will use that particular setting to configure Active Record.

3.1. Configuring Active Record

ActiveRecord::Base includes a variety of configuration options:

:table_name would make the primary key for the Customer class customerid @@ -293,154 +166,187 @@ after-initializer

table_name_prefix lets you set a global string to be prepended to table names. If you set this to northwest_, then the Customer class will look for northwest_customers as its table. The default is an empty string.

table_name_suffix lets you set a global string to be appended to table names. If you set this to _northwest, then the Customer class will look for customers_northwest as its table. The default is an empty string.

pluralize_table_names specifies whether Rails will look for singular or plural table names in the database. If set to true (the default), then the Customer class will use the customers table. If set to false, then the Customers class will use the customer table.

colorize_logging (true by default) specifies whether or not to use ANSI color codes when logging information from ActiveRecord.

default_timezone determines whether to use Time.local (if set to :local) or Time.utc (if set to :utc) when pulling dates and times from the database. The default is :local.

schema_format controls the format for dumping the database schema to a file. The options are :ruby (the default) for a database-independent version that depends on migrations, or :sql for a set of (potentially database-dependent) SQL statements.

timestamped_migrations controls whether migrations are numbered with serial integers or with timestamps. The default is true, to use timestamps, which are preferred if there are multiple developers working on the same application.

lock_optimistically controls whether ActiveRecord will use optimistic locking. By default this is true.

The MySQL adapter adds one additional configuration option:

ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans controls whether ActiveRecord will consider all tinyint(1) columns in a MySQL database to be booleans. By default this is true.

The schema dumper adds one additional configuration option:

ActiveRecord::SchemaDumper.ignore_tables accepts an array of tables that should not be included in any generated schema file. This setting is ignored unless ActiveRecord::Base.schema_format == :ruby.

4.2. Configuring Action Controller

ActionController::Base includes a number of configuration settings:

asset_host provides a string that is prepended to all of the URL-generating helpers in AssetHelper. This is designed to allow moving all javascript, CSS, and image files to a separate asset host.

consider_all_requests_local is generally set to true during development and false during production; if it is set to true, then any error will cause detailed debugging information to be dumped in the HTTP response. For finer-grained control, set this to false and implement local_request? to specify which requests should provide debugging information on errors.

allow_concurrency should be set to true to allow concurrent (threadsafe) action processing. Set to false by default.

param_parsers provides an array of handlers that can extract information from incoming HTTP requests and add it to the params hash. By default, parsers for multipart forms, URL-encoded forms, XML, and JSON are active.

default_charset specifies the default character set for all renders. The default is "utf-8".

logger accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then used to log information from Action Controller. Set to nil to disable logging.

resource_action_separator gives the token to be used between resources and actions when building or interpreting RESTful URLs. By default, this is "/".

resource_path_names is a hash of default names for several RESTful actions. By default, the new action is named new and the edit action is named edit.

request_forgery_protection_token sets the token parameter name for RequestForgery. Calling protect_from_forgery sets it to :authenticity_token by default.

optimise_named_routes turns on some optimizations in generating the routing table. It is set to true by default.

use_accept_header sets the rules for determining the response format. If this is set to true (the default) then respond_to and Request#format will take the Accept header into account. If it is set to false then the request format will be determined solely by examining params[:format]. If there is no format parameter, then the response format will be either HTML or Javascript depending on whether the request is an AJAX request.

allow_forgery_protection enables or disables CSRF protection. By default this is false in test mode and true in all other modes.

relative_url_root can be used to tell Rails that you are deploying to a subdirectory. The default is ENV[RAILS_RELATIVE_URL_ROOT].

The caching code adds two additional settings:

ActionController::Caching::Pages.page_cache_directory sets the directory where Rails will create cached pages for your web server. The default is Rails.public_path (which is usually set to RAILS_ROOT "/public"+).

ActionController::Caching::Pages.page_cache_extension sets the extension to be used when generating pages for the cache (this is ignored if the incoming request already has an extension). The default is .html.

The dispatcher includes one setting:

ActionController::Dispatcher.error_file_path gives the path where Rails will look for error files such as 404.html. The default is Rails.public_path.

The Active Record session store can also be configured:

CGI::Session::ActiveRecordStore::Session.data_column_name sets the name of the column to use to store session data. By default it is data

4.3. Configuring Action View

There are only a few configuration options for Action View, starting with four on ActionView::Base:

debug_rjs specifies whether RJS responses should be wrapped in a try/catch block that alert()s the caught exception (and then re-raises it). The default is false.

warn_cache_misses tells Rails to display a warning whenever an action results in a cache miss on your view paths. The default is false.

default_form_builder tells Rails which form builder to use by default. The default is ActionView::Helpers::FormBuilder.

The ERB template handler supplies one additional option:

ActionView::TemplateHandlers::ERB.erb_trim_mode gives the trim mode to be used by ERB. It defaults to -. See the ERB documentation for more information.

4.4. Configuring Action Mailer

There are a number of settings available on ActionMailer::Base:

template_root gives the root folder for Action Mailer templates.

logger accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then used to log information from Action Mailer. Set to nil to disable logging.

smtp_settings allows detailed configuration for the :smtp delivery method. It accepts a hash of options, which can include any of these options:

colorize_logging (true by default) specifies whether or not to use ANSI color codes when logging information from ActiveRecord.

default_timezone determines whether to use Time.local (if set to :local) or Time.utc (if set to :utc) when pulling dates and times from the database. The default is :local.

lock_optimistically controls whether ActiveRecord will use optimistic locking. By default this is true.

The MySQL adapter adds one additional configuration option:

ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans controls whether ActiveRecord will consider all tinyint(1) columns in a MySQL database to be booleans. By default this is true.

The schema dumper adds one additional configuration option:

3.2. Configuring Action Controller