Associations are a set of macro-like class methods for tying objects together through foreign keys. They express relationships like "Project has one Project Manager" or "Project belongs to a Portfolio". Each macro adds a number of methods to the class which are specialized according to the collection or association symbol and the options hash. It works much the same was as Ruby’s own attr* methods. Example:
class Project < ActiveRecord::Base
belongs_to :portfolio
has_one :project_manager
has_many :milestones
has_and_belongs_to_many :categories
end
The project class now has the following methods (and more) to ease the traversal and manipulation of its relationships:
- Project#portfolio, Project#portfolio=(portfolio), Project#portfolio.nil?
- Project#project_manager, Project#project_manager=(project_manager), Project#project_manager.nil?,
- Project#milestones.empty?, Project#milestones.size, Project#milestones, Project#milestones<<(milestone), Project#milestones.delete(milestone), Project#milestones.find(milestone_id), Project#milestones.find_all(conditions), Project#milestones.build, Project#milestones.create
- Project#categories.empty?, Project#categories.size, Project#categories, Project#categories<<(category1), Project#categories.delete(category1)
Example
Is it belongs_to or has_one?
Both express a 1-1 relationship, the difference is mostly where to place the foreign key, which goes on the table for the class saying belongs_to. Example:
class Post < ActiveRecord::Base
has_one :author
end
class Author < ActiveRecord::Base
belongs_to :post
end
The tables for these classes could look something like:
CREATE TABLE posts (
id int(11) NOT NULL auto_increment,
title varchar default NULL,
PRIMARY KEY (id)
)
CREATE TABLE authors (
id int(11) NOT NULL auto_increment,
post_id int(11) default NULL,
name varchar default NULL,
PRIMARY KEY (id)
)
Unsaved objects and associations
You can manipulate objects and associations before they are saved to the database, but there is some special behaviour you should be aware of, mostly involving the saving of associated objects.
One-to-one associations
- Assigning an object to a has_one association automatically saves that object, and the object being replaced (if there is one), in order to update their primary keys - except if the parent object is unsaved (new_record? == true).
- If either of these saves fail (due to one of the objects being invalid) the assignment statement returns false and the assignment is cancelled.
- If you wish to assign an object to a has_one association without saving it, use the association.build method (documented below).
- Assigning an object to a belongs_to association does not save the object, since the foreign key field belongs on the parent. It does not save the parent either.
Collections
- Adding an object to a collection (has_many or has_and_belongs_to_many) automatically saves that object, except if the parent object (the owner of the collection) is not yet stored in the database.
- If saving any of the objects being added to a collection (via push or similar) fails, then push returns false.
- You can add an object to a collection without automatically saving it by using the collection.build method (documented below).
- All unsaved (new_record? == true) members of the collection are automatically saved when the parent is saved.
Caching
All of the methods are built on a simple caching principle that will keep the result of the last query around unless specifically instructed not to. The cache is even shared across methods to make it even cheaper to use the macro-added methods without worrying too much about performance at the first go. Example:
project.milestones # fetches milestones from the database project.milestones.size # uses the milestone cache project.milestones.empty? # uses the milestone cache project.milestones(true).size # fetches milestones from the database project.milestones # uses the milestone cache
Modules
By default, associations will look for objects within the current module scope. Consider:
module MyApplication
module Business
class Firm < ActiveRecord::Base
has_many :clients
end
class Company < ActiveRecord::Base; end
end
end
When Firm#clients is called, it’ll in turn call MyApplication::Business::Company.find(firm.id). If you want to associate with a class in another module scope this can be done by specifying the complete class name, such as:
module MyApplication
module Business
class Firm < ActiveRecord::Base; end
end
module Billing
class Account < ActiveRecord::Base
belongs_to :firm, :class_name => "MyApplication::Business::Firm"
end
end
end
Type safety with ActiveRecord::AssociationTypeMismatch
If you attempt to assign an object to an association that doesn’t match the inferred or specified :class_name, you’ll get a ActiveRecord::AssociationTypeMismatch.
Options
All of the association macros can be specialized through options which makes more complex cases than the simple and guessable ones possible.