• Home
• What's New?
• ActiveRecord
• ActionController
• ActionView
• Database Conventions
• Testing
• Big Bag of Tricks
• Rails Version History

ActiveRecord

On this page
 - Minimal ActiveRecord
 - Attributes
 - Intercept Attributes
 - Alias Attributes
 - Delegate Attributes
 - Add Attributes
 - Update Attributes
 - Reflection on Attributes
 - Accessing attributes before they have been typecast
 - Protecting Attributes
 - Manipulate Counters
 - Toggle Booleans
 - new versus create 
 - save vs save! and create vs. create! 
 - Understanding save cascades in associations
 - Find
 - Dynamic Attribute-Based Find
 - Callbacks
 - Associations
   - One-to-One: belongs_to and has_one
   - One-to-Many: has_many
   - Many-to-Many: has_many :through and habtm
   - has_many :through, :source
   - has_many :through, :uniq
 - Association Callbacks
 - Polymorphic Associations
 - Aggregations
 - Validations
 - Acts as List
 - Acts as Tree
 - Acts as Nested Set
 - Single Table Inheritance
 - Scoping :with_scope
 
See also: 
 - the Wikipedia Active record pattern entry
 - the Official ActiveRecord Overview 
 - the ActiveRecord::Base API docs
 - the Caboose Edge ActiveRecord API docs

Minimal ActiveRecord

The simplest possible ActiveRecord model has virtually no application specific code, yet has a great deal of functionality. Here's a minimal ActiveRecord model:

class Monkey < ActiveRecord::Base end

And let's say that the monkeys table (see Database Conventions) in our database has the following structure:

+-----------------------------------------------+
| TABLE monkeys                                 |
+--------------+---------------+----------------+
| Field        | Type          | Other          |
+--------------+---------------+----------------+
| id           | integer       | primary key    |
| name         | varchar(50)   |                |
| age          | integer       |                |
| bionic_arm   | boolean       |                |
| species      | varchar(50)   |                |
+--------------+---------------+----------------+

With this simple configuration we have read and write access to all our model's attributes and we can search our existing records in a variety of ways:

monkey = Monkey.new(:name => "Buster", :species => "vervet") # or monkey = Monkey.new monkey.name = "Buster" monkey.species = "vervet" # or monkey = Monkey.new do |m| m.name = "Buster" m.species = "vervet" end # bare find selects by 'id' (default integer primary key) # find monkey with id = 1 Monkey.find(1) # find monkeys with ids 1, 4, and 7 Monkey.find(1,4,7) # find first Monkey.find(:first) # find all Monkey.find(:all) # find with conditions Monkey.find(:first, :conditions => ["species = ?", "vervet"]) # even find by any attribute in the database Monkey.find_by_name("Buster") # which is equivalent to Monkey.find(:first, :conditions => ["name = ?", "Buster"]) # you can also find all by attribute Monkey.find_all_by_species("vervet") # which is equivalent to Monkey.find(:all, :conditions => ["species = ?", "vervet"])

Attributes

ActiveRecord infers model attributes from the database. Each attribute gets a getter, setter, and query method.

monkey.name = "Steve" monkey.name #=> "Steve" monkey.name? #=> true

There are several magic attribute names that you should not inadvertently use - here is a list, more details can be found on the Database Conventions page.

created_at              updated_on               lock_version
created_on              updated_at               type
id                      #{table_name}_count      position
parent_id               lft                      rgt

Intercept Default Attribute Accessors

If you wish to manipulate an attribute before or after it is saved in the model object (and perhaps ultimately the database), you may override the default accessors and use read_attribute and write_attribute to actually change the stored attribute value. For example:

class Monkey < ActiveRecord::Base def weight=(pounds) # stupid users insist on using Imperial units in a metric world write_attribute(:weight, pounds/2.2) end def weight read_attribute(:weight) * 2.2 end end

Alias Attributes

See also:
- Ruby alias method alternative

New in Rails 1.2! Now you may use the alias_attribute method to alias an attribute name and automagically acquire getter, setter, and query methods just like a real attribute.

class Monkey < ActiveRecord::Base alias_attribute :imperial_weight, :weight end

Delegate Attributes

See Also:
 - Mailing list post on this topic

The delegate method allows you to add contained objects methods to your current objects methods. So for example (taken from the mailing list post linked above), the Mephisto blogging software pulls the year, month, and day methods up from the :published_at DateTime object into the Content object:

## Model class Content < ActiveRecord::Base # the :to options tells which object # to pull the delegated method from delegate :year, :to => :published_at delegate :month, :to => :published_at delegate :day, :to => :published_at end # Which allows one do write Content.year # as a shortcut for Content.published_at.year

Add Attributes

You may also add attributes to your model. Perhaps you want a synonym for an existing attribute or alternate access to an existing attribute:

class Monkey < ActiveRecord::Base def metric_weight=(kilos) write_attribute(:weight, kilos) end def metric_weight read_attribute(:weight) end end

Update Attributes

You may update attributes individually or in mass as a hash using either the attributes=, update_attribute, or update_attributes methods. Both of the update_* methods instantly save the record (assuming validations pass). You should be aware that calling update_* on an unsaved model will save it! New values assigned via the attributes= method must be explicitly saved.

m1 = Monkey.new m1.id #=> nil m1.attributes = {:name => "Phil" } m1.name #=> "Phil" m1.id #=> nil m1.update_attribute(:name, "Bill") m1.name #=> Bill m1.id #=> 34 (or whatever) m2 = Monkey.create(:name => "Bob", :species => "baboon") m2.id #=> 35 (or whatever) m2.name #=> "Bob" m2.attributes = {:name => "Bobby", :species => "mandrill"} m2.name #=> "Bobby" m2.reload #=> refresh attributes from the database m2.name #=> "Bob" ("Bobby" was not saved!) m2.update_attributes(:name => "Bobby", :species => "mandrill") m2.name #=> "Bobby"

Reflection on Attributes

The attribute_names method returns all of the attribute names for an ActiveRecord object and the attribute_present? method indicates if an attribute has a non-nil value or (if a String) is not empty. You may also use has_attribute? to query if a model has a particular attribute.

monkey = Monkey.new monkey.attribute_names #=> ["id", "name", "species"] monkey.attribute_present?(:name) #=> false monkey.name = "Phil" monkey.attribute_present?(:name) #=> true monkey.has_attribute?(:name) #=> true monkey.has_attribute?(:tusk) #=> false # Note that attribute_present? returns false for any value not # an attribute of the model (Monkey has no "tusk" attribute) monkey.attribute_present?(:tusk) #=> false

Accessing attributes before they have been typecast

Sometimes you want to be able to read the raw attribute data without having the column-determined typecast run its course first. That can be done by using the {attribute}_before_type_cast accessors that all attributes have.

This is especially useful in validation situations where the user might supply a string for an integer field and you want to display the original string back in an error message. Accessing the attribute normally would typecast the string to 0, which isn’t what you want.

## Model class Account < ActiveRecord::Base end ## Migration create_table "accounts" do |t| t.column "balance", :float end ## Console a = Account.create(params) a.balance_before_type_cast #=> "1234.56" (or whatever)

Protecting attributes

See also:
 - Securing your Rails application
 - a strong case for attr_accessible

Sometimes you just don't want model attributes to be easily modifiable (think passwords, account balances, and bionic arms!). You can protect your critical attributes with attr_protected or explicitly note only those attributes that are accessible with attr_accessible.

class Monkey < ActiveRecord::Base attr_protected :bionic_arm end # or class Monkey < ActiveRecord::Base attr_protected :bionic_arm end

Increment and Decrement Counters

 - for documentation on the counter_cache see the Cached Counters 
   on the Database Conventions page

There are several methods available to simplify the management of counter attributes

monkey.age #=> 5 monkey.increment(:age) #=> 6 monkey.reload monkey.age #=> 5 (must save after increment for it to take) monkey.increment(:age) #=> 6 monkey.save monkey.reload monkey.age #=> 6 # there is also a "!" version monkey.increment!(:age) #=> 6 monkey.reload monkey.age #=> 6 (increment! saves instantly) # also monkey.decrement(:age) # and monkey.decrement!(:age)

There are also the increment_counter and decrement_counter class methods - both of these methods instantly update the value in the database.

monkey_id = 5 monkey = Monkey.find(monkey_id) monkey.age #=> 5 Monkey.increment_counter(:age, monkey_id) monkey.age #=> 5 (haven't reloaded since the change) monkey.reload monkey.age #=> 6 # also Monkey.decrement_counter(:age, monkey_id)

Toggle Boolean Attributes

Boolean attributes may be flipped with the toggle and toggle! methods (the "!" method saves to the database).

monkey.bionic_arm #=> false monkey.toggle(:bionic_arm) #=> true monkey.reload #=> refresh attributes from the database monkey.bionic_arm #=> false (toggle does not save!) monkey.toggle(:bionic_arm) #=> true monkey.save monkey.reload monkey.bionic_arm #=> true # the "!" toggle! method saves instantly monkey.bionic_arm #=> true monkey.toggle!(:bionic_arm) #=> false monkey.reload monkey.bionic_arm #=> false

Model.new versus Model.create

Both new and create will return a new model object but create also saves the record to the database (assuming it passes validations), so:

m1 = Monkey.new m2 = Monkey.create m1.id #=> nil m2.id #=> 5 (or whatever) m3 = Monkey.find(m2.id) m2 == m3 #=> true m4 = Monkey.find(m1.id) #=> m4 = nil </pre> <p>You may pass a hash of attribute values into either new or create.</p> <textarea name="code" class="ruby"> attr = {:name => "Buster", :species => "vervet" } m1 = Monkey.new(attr) m2 = Monkey.create(attr) m1.name #=> "Buster" m2.species #=> "vervet"

save vs save! and create vs create!

the ! methods throw an exception on failure, the non-! methods return false on failure.

Understanding save cascades in associations

See also:
 - the "Unsaved objects and associations" section 
   on the ActiveRecord::Associations::ClassMethods API page

The save cascades resulting from association creation or assignment are not always immediately obvious! Let's see what happens in various circumstances. (You may also want to refer to the Associations section below.)

1. Assigning an object to a one-to-one association

So, if a head has_one body and a body belongs_to a head, what happens when I:

1. Assign a new head to an existing body
2. Assign a new body to an existing head

## Models class Head < ActiveRecord::Base has_one :body end class Body < ActiveRecord::Base belongs_to :head end ## Migrations create_table "heads" do |t| t.column "name", :string end create_table "bodies" do |t| t.column "name", :string t.column "head_id", :integer end ## Console # existing (in the db) body, new head b = Body.create h = Head.new b.head = h b.reload b.head #=> nil # existing (in the db) head, new body h = Head.create b = Body.new h.body = b h.reload h.body #=> Body b b.reload b.head #=> Head h

From this example we learn that in a one-to-one relationship that:

1. adding the has_one object to the belongs_to object does not save the has_one object
2. adding the belongs_to object to the has_one object instantly saves the belongs_to object

Or, another way of putting it is that only the object with the foreign key in the database is saved when added to other objects.

2. Using the build method to assign to a one-to-one association without saving

We know (from just above) that adding the has_one object to the belongs_to object does not save the has_one object, so that situation is not in question here. But, is it possible to assign a new belongs_to object to a has_one object without saving? (Using the same models and tables as just above...)

## Console # Head has_one Body, Body belongs_to Head h = Head.create b = h.build_body h.reload h.body #=> nil # of course, it works the other way too # (but this association is never automatically saved) b = Body.create h = b.build_head b.reload b.head #=> nil

3. Assigning an object to a has_many association

has_many and has_one associations work in pretty much the save way. So, like has_one, assigning the has_many object to the belongs_to object will not instantly save it, while the reverse will. The build method may be used here as well to stave off saving the belongs_to object.

Why would we want to defer saving? Suppose you have an object that belongs_to more than one other object and you want to ensure all the associations are properly created when saving. For example, let's say we have a (probably poorly designed) robot-building application and we want to make sure that when we create our robot we get a body and two arms at one go.

## Models class Body < ActiveRecord::Base has_one :left_arm, :class_name => "Arm" has_one :right_arm, :class_name => "Arm" end class Arm < ActiveRecord::Base belongs_to :body end ## Migrations create_table "bodies" do |t| t.column "name", :string end create_table "arms" do |t| t.column "side", :string t.column "body_id", :integer end ## Console b = Body.new b.build_left_arm b.build_right_arm # nothing is saved now, but assuming no errors have # been thrown, everything is going well. Saving the # new body now will save everything into the database # in one insert b.save

4. Assigning an object to a has_and_belongs_to_many association

Whether new associations are saved or not in a habtm relationship depends on the save status of the collecting object.

1. If the collecting object is unsaved, new associations will not be saved
2. If the collecting object is saved, new associations will be instantly saved

## Models class Player < ActiveRecord::Base has_and_belongs_to_many :teams end class Team < ActiveRecord::Base has_and_belongs_to_many :players end ## Migrations create_table "players" do |t| t.column "name", :string end create_table "teams" do |t| t.column "name", :string end create_table "players_teams", :id => false do |t| t.column "player_id", :integer t.column "team_id", :integer end ## Console # unsaved team, players will not be saved until team is t = Team.new # add some players t.players << Player.new t.players << Player.new # (assuming empty db at start) Player.count #=> 0 # now save everything t.save Player.count #=> 2 # team in db, added players will be instantly saved t = Team.create # add some players t.players << Player.new t.players << Player.new # new players already saved # (empty db at start of this 2nd example) Player.count #=> 2

5. Assigning an object to a has_many :through association

Here are the save cascade rules for has_many :through.

1. The join model will not automatically save new associations
2. has_many :through objects will not automatically save pushed associations. In fact, these will be lost unless the associated object is saved!
3. In Rails 1.2, the << operator should work as for habtm (above)

## Models class Player < ActiveRecord::Base has_many :contracts has_many :teams, :through => :contracts end class Team < ActiveRecord::Base has_many :contracts has_many :players, :through => :contracts end class Contract < ActiveRecord::Base belongs_to :player belongs_to :team end ## Migrations create_table "players" do |t| t.column "name", :string end create_table "teams" do |t| t.column "name", :string end create_table "contracts" do |t| t.column "player_id", :integer t.column "team_id", :integer end ## Console # new join model will not save new associations c = Contract.new c.team = Team.new c.player = Player.new # everything unsaved so far Player.count #=> 0 Team.count #=> 0 # save contract, everything gets saved c.save Player.count #=> 1 Team.count #=> 1 # adding via push does not automatically save t = Team.new # or t = Team.create # add some players t.players.push(Player.new) t.players.push(Player.new) # new players not automatically saved # (empty db at beginning of this chunk) Player.count #=> 0 # save it all t.save # unsaved players lost!! Player.count #=> 0

Find

See also:
- Under the hood: ActiveRecord::Base.find, Part 1 by Jamis Buck
- Under the hood: ActiveRecord::Base.find, Part 2 by Jamis Buck
- Under the hood: ActiveRecord::Base.find, Part 3 by Jamis Buck

ActiveRecord gives you an incredible range of options for selecting records from your database with its basic find method, and you may even drop into explicit SQL with find_by_sql if you must (although this is generally discouraged).

The most basic find selects records by primary key (the autoincremented integer field 'id' by default). If you attempt to access only one record.

Monkey.find(1)

then you will receive a single Monkey object (or ActiveRecord::RecordNotFound error if there is no Monkey with id = 1 to be found). Thus, in some cases you may want to ensure that a record exists for a given id before trying to retrieve it from the database,

try_id = 5 if Monkey.exists?(try_id) monkey = Monkey.find(try_id) end

If you pass in more than one id or an array of ids then you will receive an array in return

Monkey.find(1,3,5) # or Monkey.find([1,3,5]) # or to retrieve a single object in an array Monkey.find([1])

You may also retrieve the first record or all records with the standard find syntax. This syntax replaces the deprecated find_first and find_all methods

Monkey.find(:first) Monkey.find(:all)

find has many useful options, listed here and described below.

find options
- :conditions
- :order
- :group
- :limit
- :offset
- :joins
- :include
- :select
- :readonly

Finding with :conditions allows you to supply a SQL WHERE fragment to limit the result.

Monkey.find(:all, :conditions => "species = 'vervet'") Monkey.find(:all, :conditions => ["species = ?" , "vervet"])

The conditions array format is not necessary, but will sanitize user input and should always be used whenever you do not have complete control over the input

# ok if there is no user input Monkey.find(:all, :conditions => "species = 'vervet'") # but if there is user input, use the array form Monkey.find(:all, :conditions => ["species = ?", user_selected_species])

New in Rails 1.2 - Conditions takes a hash! The comparison is limited to equality and AND.

Monkey.find(:first, :conditions => ["name = ? AND species = ?", "Phil", "vervet"]) # can be written for Rails 1.2 as Monkey.find(:first, :conditions => {:name => "Phil", :species => "vervet"}) # however, this OR condition must stay in the array format Monkey.find(:first, :conditions => ["species = ? OR species = ?", "baboon", "vervet"])

New in Rails 1.2 - Conditions take arrays!

Monkey.find(:first, :conditions => ["species IN (?)", ["baboon", "vervet"] ])

The :order option takes a valid SQL fragment

Monkey.find(:all, :order => "name") # ascending(ASC) is typically the default # but descending(DESC) may be used as well Monkey.find(:all, :order => "name DESC") # multiple orders are possible Monkey.find(:all, :order => "name DESC, species")

The :group option uses the GROUP BY SQL syntax to group the result.

Monkey.find(:all, :group => "species")

The :limit option sets the maximum size of the result set

Monkey.find(:all, :limit => 20) # plays well with the :offset option Monkey.find(:all, :offset => 20, :limit => 20)

The :offset option sets where the select should begin.

Monkey.find(:all, :offset => 20) # plays well with the :limit option Monkey.find(:all, :offset => 20, :limit => 20)

Discouraged: The :joins option takes a SQL JOIN fragment. Whenever possible use :include's eager loading (see Associations below).

Monkey.find(:all, :joins => "LEFT JOIN offspring ON offspring.parent_id = id") # :joins implies :readonly => true, # you may explicitly pass :readonly => false to override this Monkey.find(:all, :joins => "LEFT JOIN offspring ON offspring.parent_id = id", :readonly => false)

The :include option performs eager loading on associations using LEFT OUTER JOINs. See the "Eager loading of associations" section in the official ActiveRecord::Association documentation as well as Associations below for more information. Primarily you will use the :include option to reduce the number of database hits for records associated with your primary record. In my example here, if I am planning to count the offspring of every monkey in my database I may load all these offspring in one database query rather than going back and hitting the database for each individual monkey's offspring. You should be aware that using :include may cause introduce ambiguity in :conditions and :order options (see the "Eager loading of associations" section in the official ActiveRecord::Associations documentation).

Monkey.find(:all, :include => :offspring) # include more than one association Monkey.find(:all, :include => [:offspring, :group]

The :select option is by default the "*" in "SELECT * FROM" but can be replaced by any valid SQL fragment

Monkey.find(:all, :select => "name AS given_name")

The :readonly option locks the returned records disallowing any changes.

Monkey.find(:all, :readonly => true)

Dynamic Attribute-Based Find

The dynamic find methods are syntactic sugar aimed at making your queries easier to write and easier to read. It is easiest to show them in use

## 1. find_by_{attribute} Monkey.find_by_name("Phil") # is equivalent to Monkey.find(:first, :conditions => [ "name = ?", "Phil" ]) # you can add any of the usual find options to these dynamic finders Monkey.find_by_name("Phil", :order => "species DESC") ## 2. find_all_by_{attribute} Monkey.find_all_by_species("vervet") # is equivalent to Monkey.find(:all, :conditions => [ "species = ?", "vervet" ]) ## 4. find_by_{attribute}_and_{attribute} or ## find_all_by_{attribute}_and_{attribute} Monkey.find_by_name_and_species("Phil", "vervet") # is equivalent to Monkey.find(:first, :conditions => [ "name = ? AND species = ?", "Phil", "vervet" ]) # you can chain as many together as you wish, although # you're probably not helping readability after a certain point ## 5. find_or_create_by_{attribute} # if the object doesn't exist, create it Monkey.find_or_create_by_name("Phil") # you can _and_ this one too Monkey.find_or_create_by_name_and_species("Phil", "vervet") # ** New in Rails 1.2 ** ## 6. find_or_initialize_by_{attribute} # because sometimes you don't want to instantly save a new object # (create saves, initialize doesn't) Monkey.find_or_initialize_by_name("Phil")

Callbacks

From the API documentation, "Callbacks are hooks into the lifecycle of an Active Record object that allows you to trigger logic before or after an alteration of the object state." There are callbacks for: validate, create, save, update, destroy, find, new/initialize, and associations (Association Callbacks are discussed in the Associations section below).

You may configure most of these callbacks (excluding find, initialize, and association callbacks) in two different ways: (1) overwrite the default method or (2) register with the macros. The macros are more powerful and more commonly used, especially as the macros add their behavior into a callback hierarchy that is maintained through a class inheritance hierarchy. That is, if you register callbacks for the Animal class (which inherits from ActiveRecord::Base) and subsequently define a Monkey class (which inherits from Animal), then Monkey will also inherit the Animal callbacks.

The callback macros can be used in four different ways (see the very clear discussion in the "Types of callbacks" section on the ActiveRecord::Callbacks API page)

1. symbol reference to a protected or private method in the model
2. an object to be messaged with the callback method and record
3. a method string
4. a method Proc

The validation callback hierarchy

These series are triggered by calls to:
 object.valid?

New Record                      Existing Record
-----------------------------       -----------------------------
 before_validation                   before_validation
 before_validation_on_create         before_validation_on_update
 << object validated here >>         << object validated here >>
 after_validation                    after_validation
 after_validation_on_create          after_validation_on_update

This series is triggered by calls to:
 Model.create
 object.save (if not previously saved)

before_validation
before_validation_on_create
<< object validated here >>  
after_validation 
after_validation_on_create 
before_save    
before_create 
<< db record created here >> 
after_create
after_save

This series is triggered by calls to:
 object.save (if previously saved)
 object.update_attributes

before_validation
before_validation_on_update
<< object validated here >>
after_validation
after_validation_on_update
before_save
before_update
<< db record saved/updated here >>
after_update
after_save

A save! call triggers the validation series twice. If save! is called on a new record, the new record validation series with *_on_create methods is called twice.

This series is triggered by calls to:
 object.save!

before_validation
before_validation_on_update
<< object validated here >>
after_validation
after_validation_on_update
before_validation
before_validation_on_update
<< object validated here >>
after_validation
after_validation_on_update
before_save
before_update
<< db record saved/updated here >>
after_update
after_save

Several of the save/update methods appear to bypass validation (or at least the validation callbacks) and only call the save callbacks.

This series is triggered by calls to:
 object.increment!
 object.decrement!
 object.toggle!
 object.update_attribute

before_save
before_update
<< db record saved/updated here >>
after_update
after_save

The object.update callback hierarchy only triggers the update callbacks.

This series is triggered by calls to:
 object.update

before_update
<< db record updated here >>
after_update

However, the model update class method triggers a full series of callbacks.

This series is triggered by calls to:
 Model.update

after_find             (if defined)
after_initialize       (if defined)
before_validation
before_validation_on_update
<< object validated here >>
after_validation
after_validation_on_update
before_save
before_update
<< db record saved/updated here >>
after_update
after_save

increment_counter and decrement_counter bypass all callbacks

These methods bypass all callbacks:
 Model.decrement_counter
 Model.increment_counter

This series is triggered by calls to:
 object.destroy

before_destroy
<< record is deleted here >> 
after_destroy

This series is triggered by calls to:
 Model.destroy
 Model.destroy_all

after_find             (if defined)
after_initialize       (if defined)
before_destroy
<< record is deleted here >> 
after_destroy

These don't trigger any callbacks:
 Model.delete
 Model.delete_all

The after_find and after_initialize callbacks may will only be called if the default method is overwritten (no macros here).

Triggered by a call to:
 Model.new

after_initialize       (if defined)

--------------------------------------------

Triggered by a call to:
 object.reload
 Model.find

after_find             (if defined)
after_initialize       (if defined)

Associations

See also:
 - Amy Hoy's Associations Cheat Sheet [pdf]
 - Josh Susser's many informative posts on associations
 - Advanced Topic: Extending ActiveRecord associations by Jamis Buck
 - Advanced Topic: Self-Referential Joins by Leon

There are four associations: belongs_to, has_one, has_many, and has_and_belongs_to_many (often abbreviated habtm - but not in code!). The API documentation for the association methods is very good.

One-to-One: belongs_to and has_one

belongs_to and has_one both express a one-to-one relationship with the main difference being which table has the foreign key, so let's try some variants. First, a one-to-one association that is only accessible from one of the objects.

## Models: class Head < ActiveRecord::Base end class Body < ActiveRecord::Base belongs_to :head end ## Migrations: create_table "heads" do |t| end create_table "bodies" do |t| t.column "head_id", :integer end ## Console: # set up h = Head.new b = Body.new b.head = h # in use b.head #=> returns Head object h.body #=> NoMethodError

If we add the has_one association to the non-foreign-key-containing-model, we achieve a one-to-one association with access from both objects.

## Models: class Head < ActiveRecord::Base has_one :body end class Body < ActiveRecord::Base belongs_to :head end # Same tables as before (if you're trying this out, # all you need to do is add the "has_one :body" to head.rb) ## Console: # set up h = Head.new b = Body.new b.head = h # in use b.head #=> returns Head object h.body #=> nil (this isn't populated until # the body record is saved) b.save h.body #=> returns Body object

Alternatively, you can set up models (and matching) tables with dueling belongs_to associations. This "works" (doesn't throw errors) but the behavior is probably not desirable in most situations (I say most because I imagine there are some setups where you may want this behavior). Observe.

## Models: class Head < ActiveRecord::Base belongs_to :body end class Body < ActiveRecord::Base belongs_to :head end ## Migrations: create_table "heads" do |t| t.column "body_id", :integer end create_table "bodies" do |t| t.column "head_id", :integer end ## Console: # set up h1 = Head.new b1 = Body.new b1.head = h1 h2 = Head.new b2 = Body.new b2.head = h2 # in use b1.head #=> h1 Head object b2.head #=> h2 Head object h1.body #=> nil b1.save h1.body #=> nil (still) # here's where this setup's behavior is odd (totally logical, but still odd) h1.body = b2 h2.body = b1 b1.head #=> h1 Head object h1.body #=> b2 Body object (!! - the body's # head and the head's body are # completely independent!)

The final combination of dueling has_one models (with appropriate tables) will also be accepted by rails (won't immediately throw an error) but doesn't behave in a way that is at all useful (and it is obvious why: there is no place for rails to store the foreign key!)

# DEMONSTRATION ONLY - DON'T USE THIS SETUP # ## Models: class Head < ActiveRecord::Base has_one :body end class Body < ActiveRecord::Base has_one :head end ## Migrations: create_table "heads" do |t| t.column "name", :string end create_table "bodies" do |t| t.column "name", :string end ## Console: # set up h = Head.new b = Body.new # these work (if no association assignment has been made) b.save #=> true h.save #=> true # no assignment has been made, accessors "work" b.head #=> nil h.body #=> nil # assignment seems to work b.head = h b.head #=> h Head object # here's where it dies b.save #=> SystemStackError (ultimately # attributable to no place in the # record to save id)

Rails will let you shoot yourself in the foot! Here we use dueling has_one models and (inappropriately) put a foreign key in one of the models. This "works" and it is possible you won't immediately run into the situation where it breaks - but when you do, it's going to be very very difficult to track down!

# DEMONSTRATION ONLY - DON'T USE THIS SETUP # ## Models: class Head < ActiveRecord::Base has_one :body end class Body < ActiveRecord::Base has_one :head end ## Migrations: create_table "heads" do |t| end create_table "bodies" do |t| t.column "head_id", :integer end ## Console: # set up h = Head.new b = Body.new # this works h.body #=> nil # this doesn't b.head #=> SQLException (tries to access the # heads "body_id" column which # doesn't exist) # assignment works in one direction h.body = b h.body #=> b Body object # saving the relationship works h.save #=> true h.body #=> b Body object # but assignment doesn't work in the other direction b.head = h #=> SQLException (tries to access the # heads "body_id" column which # doesn't exist)

One-to-Many: has_many

A Company has_many Employees. A Dog has_many Fleas. A Blog has_many Articles. You get the idea. has_many works pretty much the same way as has_one, and like has_one is typically paired with a belongs_to in the matching model. Here's a simple example.

## Models: class Employee < ActiveRecord::Base belongs_to :company end class Company < ActiveRecord::Base has_many :employees end ## Migrations: create_table "employees" do |t| t.column "name", :string t.column "company_id", :integer end create_table "companies" do |t| t.column "name", :string end ## Console: c = Company.create(:name => "Das Kompanie") e = Employee.create(:name => "Commandante") e.company = c e.save c.reload c.employees #=> [ Employee "Commandante" ]

Many-to-Many: has_many :through and habtm

See also:
 - Josh Susser's post on magic-join-model-creation
 - Josh Susser's post on join-models-not-proxy-collections
 - Josh Susser's post on many-to-many-dance-off
 - this mailing list post from DHH just prior to the introduction of has_many :through in Rails 1.1

I would suggest using has_many :through over habtm unless you can clearly articulate your reasons for preferring habtm (slightly easier model configuration is not a good reason).

Let's first look at has_and_belongs_to_many

## Models: class Player < ActiveRecord::Base has_and_belongs_to_many :teams end class Team < ActiveRecord::Base has_and_belongs_to_many :players has_and_belongs_to_many :games end class Game < ActiveRecord::Base has_and_belongs_to_many :teams end ## Migrations: create_table "players" do |t| t.column "name", :string end create_table "teams" do |t| t.column "name", :string end create_table "games" do |t| t.column "venue", :string end # habtm join tables # the name of the join table is always {table one}_{table two} in alphabetical order create_table "players_teams", :id => false do |t| t.column "player_id", :integer t.column "team_id", :integer end create_table "games_teams", :id => false do |t| t.column "game_id", :integer t.column "team_id", :integer end ## Console: p1 = Player.create(:name => "p1") p2 = Player.create(:name => "p2") t1 = Team.create(:name => "t1") t1.players #=> [] t1.players.push(p1) t1.players.push(p2) t1.players #=> [ p1, p2 ] # or we could have added players using the << operator t1.players << p1 << p2 t1.players #=> [ p1, p2 ] # adding objects to a habtm association performs a save # we can see this by reloading the t1 object - if the # associations had not been saved, the players array would # be empty, but it isn't t1.reload t1.players #=> [ p1, p2 ] # and we can also access a player's teams p1.teams #=> [ t1 ] # and, after we create a game and add it to a team, # we can access through the whole chain g1 = Game.create t1.games << g1 t1.games #=> [ g1 ] p1.teams.find(:first).games #=> [ g1 ] # if we wanted all of a player's games without regard for # the team she represented at the time, we could add this # method to the Player model def games (teams.collect { |t| t.games }).flatten end # and then use it as such p1.games #=> [ g1 ]

Now let's look at the same idea implemented using has_many :through.

## Models: class Player < ActiveRecord::Base has_many :partnerships has_many :teams, :through => :partnerships end class Partnership < ActiveRecord::Base belongs_to :player belongs_to :team end class Team < ActiveRecord::Base has_many :partnerships has_many :players, :through => :partnerships has_many :encounters has_many :games, :through => :encounters end class Encounter < ActiveRecord::Base belongs_to :team belongs_to :game end class Game < ActiveRecord::Base has_many :encounters has_many :teams, :through => :encounter end ## Migrations: create_table "players" do |t| t.column "name", :string end create_table "teams" do |t| t.column "name", :string end create_table "partnerships" do |t| t.column "player_id", :integer t.column "team_id", :integer end create_table "games" do |t| t.column "venue", :string end create_table "encounters" do |t| t.column "game_id", :integer t.column "team_id", :integer end ## Console: p1 = Player.create(:name => "p1") p2 = Player.create(:name => "p2") t1 = Team.create(:name => "t1") t1.players #=> [] # in Rails 1.2 you will be able to use <<, push, and concat from # habtm in has_many :through (see below), but for pre-1.2 you must # use these methods Partnership.create(:player => p1, :team => t1) Partnership.create(:player => p2, :team => t1) t1.players #=> [ p1, p2 ] # or we could have added players through the association t1.partnerships.create(:player => p1) t1.partnerships.create(:player => p2) t1.players #=> [ p1, p2 ] # and we can also access a player's teams p1.teams #=> [ t1 ] # and, after we create a game and add it to a team, # we can access through the whole chain g1 = Game.create t1.encounters.create(:game => g1) t1.games #=> [ g1 ] p1.teams.find(:first).games #=> [ g1 ] # if we wanted all of a player's games without regard for # the team she represented at the time, we could add this # method to the Player model def games (teams.collect { |t| t.games }).flatten end # and then use it as such p1.games #=> [ g1 ]

has_many :through, :source

There are many circumstances where you might have multiple references to the same table, the :source option lets you do it with style! See the example:

## Models: class Person < ActiveRecord::Base end class Company < ActiveRecord::Base has_many :employments has_many :employees, :through => :employments, :source => :person has_many :contracts has_many :customers, :through => :contracts, :source => :person end class Employment < ActiveRecord::Base belongs_to :person belongs_to :company end class Contract < ActiveRecord::Base belongs_to :person belongs_to :company end ## Migrations: create_table "people" do |t| t.column "name", :string end create_table "companies" do |t| t.column "name", :string end create_table "employments" do |t| t.column "person_id", :integer t.column "company_id", :integer end create_table "contracts" do |t| t.column "person_id", :integer t.column "company_id", :integer end ## Console: empl = Person.create(:name => "employee") cust = Person.create(:name => "customer") comp = Company.create(:name => "conglomerate") comp.employees << empl comp.customers << cust comp.employees #=> [ Person "employee" ] comp.customers #=> [ Person "customer" ]

has_many :through, :uniq

The :uniq (new in 1.2) option to has_many :through will eliminate duplicates from the :through collection

## Models: class Item < ActiveRecord::Base belongs_to :category belongs_to :supplier end class Category < ActiveRecord::Base has_many :items has_many :suppliers, :through => :items, :uniq end class Supplier < ActiveRecord::Base has_many :items has_many :categories, :through => :items, :uniq end ## Migrations: create_table "items" do |t| t.column "name", :string t.column "category_id", :integer t.column "supplier_id", :integer end create_table "categories" do |t| t.column "name", :string end create_table "suppliers" do |t| t.column "name", :string end ## Console: c = Category.create(:name => "Household") s = Supplier.create(:name => "Big Co") i1 = Item.create() i2 = Item.create() i1.supplier = i2.supplier = s i1.category = i2.category = c i1.save; i2.save c.suppliers.count #=> 1 (this would be 2 withough the :uniq option)

Association Callbacks

There are four callbacks you can apply to your association definition

 before_add
 after_add
 before_remove
 after_remove

Typically you will supply these with the name of an instance method, but you can also pass them a Proc. You may pass multiple methods in an array. If an exception is thrown in a before_add or before_remove callback, the object will not be added or removed respectively.

class Monkey < ActiveRecord::Base has_many :friends, :before_add => :verify_intentions end class Company < ActiveRecord::Base has_many :clients, :after_add => [ :verify_address, :update_christmas_card_list, Proc.new { |co, client| co.value += client.value } ] end

Polymorphic Associations

See also:
 - the Understanding Polymorphic Associations page on the rails wiki

Use a polymorphic association when you want one type of object to be able to belong_to more than one other type of object. In the example I have Items that may be owned by either an Individual or a Company. (Tags as taggable are often implemented as polymorphic associations.)

## Models # declare Item as polymorphic class Item < ActiveRecord::Base belongs_to :owner, :polymorphic => true end # associate other objects as owners class Individual < ActiveRecord::Base has_many :items, :as => :owner end class Company < ActiveRecord::Base has_many :items, :as => :owner end ## Migrations create_table "items" do |t| t.column "description", :string t.column "owner_type", :string t.column "owner_id", :integer end create_table "companies" do |t| t.column "name", :string end create_table "individuals" do |t| t.column "name", :string end ## Console item = Item.create i = Individual.create c = Company.create # assign the item to an Individual item.owner = i item.owner #=> Individual i # change the owner to a company item.owner = c item.owner #=> Company c

Aggregations

See also:
 - the ActiveRecord::Aggregations Class Methods page

Aggregations allow you to compose models of ruby classes in part or entirety. In the Globalize plugin, aggregations are used to provide currency localization. Here is a (highly simplified) illustration of how they've used aggregations: (You should check out the full implementation in the globalize projects svn repository. Their Currency class actually takes care of the details needed to localize currency; my Money class here is only fleshed out enough to be usable - although probably not useful!!).

## Encapsulated Class class Money attr_reader :cents, :currency def initialize(cents, currency) @cents = cents.nil? ? 0 : cents.to_i @currency = currency.nil? ? "$" : currency.to_s end def amount return "#{currency}#{dollar_part}.#{cent_part}" end private def dollar_part cents / 100 end def cent_part cents % 100 end end ## Model class Product < ActiveRecord::Base composed_of :price, :class_name => "Money", :mapping => [ %w(price cents), %w(currency currency) ] end ## Migration create_table "products" do |t| t.column "name", :string t.column "price", :integer t.column "currency", :string end ## Console p = Product.create(:name => "my product", :price => Money.new(1000)) p.price #=> Money object p.price.amount #=> "$10.0"

Thus, aggregations:

1. are constructed using the composed_of macro.
2. can feed model values through a ruby class
3. can be told the proper class name with the :class_name option if it cannot be inferred from the aggregation
4. can be told which db values should be handled by the aggregate in the :mapping option
5. can be told what db values and in which order should be fed to the aggregate's initialize method in the :mapping option

Validations

See also:
 - the Validations API page
 - the Validations Class Methods API page

Validations help you maintain your data by ensuring that no improper values make it to the database through ActiveRecord. The stock API documentation for validations is very good (each method name below is linked to the API docs.) The validation methods available to you are:

 - validates_acceptance_of
 - validates_associated
 - validates_confirmation_of
 - validates_each
 - validates_exclusion_of
 - validates_format_of
 - validates_inclusion_of
 - validates_length_of
 - validates_numericality_of
 - validates_presence_of
 - validates_size_of
 - validates_uniqueness_of

Acts as List

The acts_as_list macro allows for the easy creation of list structures in your rails application. We'll start with a basic one model, one table list structure and build from there.

See also:
 - the Acts as List section on the Database Conventions page.
 - the class method API docs for acts_as_list
 - the instance method API docs for acts_as_list 

Before we look at some examples, here are the methods available to acts_as_list models.

 - in_list?
 - first?
 - last?

 - insert_at
 - remove_from_list

 - increment_position
 - decrement_position

 - higher_item
 - lower_item

 - move_higher
 - move_lower
 - move_to_top
 - move_to_bottom

First a simple one model, one table example

## Models class Chapter < ActiveRecord::Base acts_as_list end ## Migrations create_table "chapters" do |t| t.column "title", :string t.column "position", :integer end ## Console c1 = Chapter.create c2 = Chapter.create c1.position #=> 1 c2.position #=> 2 c2.move_higher c2.position #=> 1 c1.reload.position #=> 2

Now a two model, two table example

## Models class Book < ActiveRecord::Base has_many :chapters, :order => "position" end class Chapter < ActiveRecord::Base belongs_to :book acts_as_list :scope => :book end ## Migrations create_table "books" do |t| t.column "title", :string end create_table "chapters" do |t| t.column "title", :string t.column "position", :integer t.column "book_id", :integer end ## Console book = Book.create book.chapters.push(Chapter.create(:title => "1")) book.chapters.push(Chapter.create(:title => "2")) book.chapters #=> [ Chapter "1", Chapter "2" ] book.chapters.first.move_to_bottom book.chapters #=> [ Chapter "2", Chapter "1" ]

Acts as Tree

ActiveRecord has built-in support for a tree structure.

See also:
 - the Acts as Tree section on the Database Conventions page.
 - the class method API docs for acts_as_tree
 - the instance method API docs for acts_as_tree 

Before we look at some examples, here are the methods available to acts_as_tree models.

 - root
 - parent
 - ancestors
 - children
 - self_and_siblings
 - siblings

## Models class Monkey < ActiveRecord::Base acts_as_tree end ## Migrations create_table "monkeys" do |t| t.column "parent_id", :integer end ## Console m1 = Monkey.create m2 = Monkey.create m1.children.push(m2) m1.children #=> [ Monkey m2 ] m2.parent #=> [ Monkey m1 ]

Acts as Nested Set

ActiveRecord has built-in support for a nested set structure.

See also:
 - the Acts as Nested Set section on the Database Conventions page.
 - the class method API docs for acts_as_nested_set
 - the instance method API docs for acts_as_nested_set 

Before we look at some examples, here are the methods available to acts_as_nested_set models.

 - root?
 - child?
 - unknown?

 - add_child

 - all_children
 - direct_children
 - full_set

 - children_count
 - before_destroy  (implements this callback such that pruning 
                    a branch doesn't mess up the counts)

## Models class Comment < ActiveRecord::Base acts_as_nested_set end ## Migrations create_table "comments" do |t| t.column "parent_id", :integer t.column "lft", :integer t.column "rgt", :integer end ## Console c1 = Comment.create c2 = Comment.create c3 = Comment.create c1.add_child(c2) c1.root? #=> true c1.child? #=> false c2.root? #=> false c2.child? #=> true c3.root? #=> false c3.child? #=> false c3.unknown? #=> true c1.all_children #=> [ Comment c2 ] c1.full_set #=> [ Comment c1, Autobot c2 ]

Single Table Inheritance

See also:
 - the Single Table Inheritance section on the Database Conventions page.
 - the "Single table inheritance" section in the ActiveRecord::Base API docs.
 - Single Table Inheritance in Rails S5 presentation by Skip Baney

ActiveRecord includes support for the Single Table Inheritance pattern. Skip Baney has a very good online slideshow presenting Single Table Inheritance In Rails.

## Model class Primate < ActiveRecord::Base end class OldWorldMonkey < Primate end class Baboon < OldWorldMonkey end ## Migration create_table "primates" do |t| t.column "type", :string, :default => "Primate" end ## Console Primate.create OldWorldMonkey.create Baboon.create # use [:type] instead of .type to avoid accessing # the deprecated standard ruby Object#type Primate.find(:all).collect { |e| e[:type] } #=> ["Primate", "OldWorldMonkey", "Baboon"] OldWorldMonkey.find(:all).collect { |e| e[:type] } #=> ["OldWorldMonkey", "Baboon"] Baboon.find(:all).collect { |e| e[:type] } #=> ["Baboon"]

Scoping :with_scope

See:
 - maiha's caboose posting on nested with_scope
 - the API with_scope docs
 - with_scope with scope by Chris Wanstrath

More coming soon! But until then, maiha'a post and the api docs ably explain this concept.