Skip to content
Browse files

Improve association documentation, closes #7022. [hasmanyjosh]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@5939 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
1 parent 6019c26 commit 51d840e272941023ad62d021fa2b4a491fe9953a @NZKoz NZKoz committed Jan 15, 2007
Showing with 65 additions and 1 deletion.
  1. +65 −1 activerecord/lib/active_record/associations.rb
View
66 activerecord/lib/active_record/associations.rb
@@ -93,7 +93,71 @@ def clear_association_cache #:nodoc:
#
# link:files/examples/associations.png
#
- # == Is it belongs_to or has_one?
+ # == Cardinality and associations
+ #
+ # ActiveRecord associations can be used to describe relations with one-to-one, one-to-many
+ # and many-to-many cardinality. Each model uses an association to describe its role in
+ # the relation. In each case, the belongs_to association is used in the model that has
+ # the foreign key
+ #
+ # === One-to-one
+ #
+ # Use has_one in the base, and belongs_to in the associated model.
+ #
+ # class Employee < ActiveRecord::Base
+ # has_one :office
+ # end
+ # class Office < ActiveRecord::Base
+ # belongs_to :employee # foreign key - employee_id
+ # end
+ #
+ # === One-to-many
+ #
+ # Use has_many in the base, and belongs_to in the associated model.
+ #
+ # class Manager < ActiveRecord::Base
+ # has_many :employees
+ # end
+ # class Employee < ActiveRecord::Base
+ # belongs_to :manager # foreign key - employee_id
+ # end
+ #
+ # === Many-to-many
+ #
+ # There are two ways to build a many-to-many relationship.
+ #
+ # The first way uses a has_many association with the :through option and a join model, so
+ # there are two stages of associations.
+ #
+ # class Assignment < ActiveRecord::Base
+ # belongs_to :programmer # foreign key - programmer_id
+ # belongs_to :project # foreign key - project_id
+ # end
+ # class Programmer < ActiveRecord::Base
+ # has_many :assignments
+ # has_many :projects, :through => :assignments
+ # end
+ # class Project < ActiveRecord::Base
+ # has_many :assignments
+ # has_many :programmers, :through => :assignments
+ # end
+ #
+ # For the second way, use has_and_belongs_to_many in both models. This requires a join table
+ # that has no corresponding model or primary key.
+ #
+ # class Programmer < ActiveRecord::Base
+ # has_and_belongs_to_many :projects # foreign keys in the join table
+ # end
+ # class Project < ActiveRecord::Base
+ # has_and_belongs_to_many :programmers # foreign keys in the join table
+ # end
+ #
+ # It is not always a simple decision which way of building a many-to-many relationship is best.
+ # But if you need to work with the relationship model as its own entity, then you'll need to
+ # use has_many :through. Use has_and_belongs_to_many when working with legacy schemas or when
+ # you never work directly with the relationship itself.
+ #
+ # == Is it a belongs_to or has_one association?
#
# 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:

0 comments on commit 51d840e

Please sign in to comment.
Something went wrong with that request. Please try again.