instance method has_one

Specifies a one-to-one association with another class. This method should only be used if the other class contains the foreign key. If the current class contains the foreign key, then you should use belongs_to instead. See also ActiveRecord::Associations::ClassMethods’s overview on when to use has_one and when to use belongs_to.

The following methods for retrieval and query of a single associated object will be added:

association(force_reload = false)

Returns the associated object. nil is returned if none is found.

association=(associate)

Assigns the associate object, extracts the primary key, sets it as the foreign key, and saves the associate object.

association.nil?

Returns true if there is no associated object.

build_association(attributes = {})

Returns a new object of the associated type that has been instantiated with attributes and linked to this object through a foreign key, but has not yet been saved. Note: This ONLY works if an association already exists. It will NOT work if the association is nil.

create_association(attributes = {})

Returns a new object of the associated type that has been instantiated with attributes, linked to this object through a foreign key, and that has already been saved (if it passed the validation).

(association is replaced with the symbol passed as the first argument, so has_one :manager would add among others manager.nil?.)

Example

An Account class declares has_one :beneficiary, which will add:

• Account#beneficiary (similar to Beneficiary.find(:first, :conditions => "account_id = #{id}"))

• Account#beneficiary=(beneficiary) (similar to beneficiary.account_id = account.id; beneficiary.save)

• Account#beneficiary.nil?

• Account#build_beneficiary (similar to Beneficiary.new("account_id" => id))

• Account#create_beneficiary (similar to b = Beneficiary.new("account_id" => id); b.save; b)

Options

The declaration can also include an options hash to specialize the behavior of the association.

Options are:

:class_name

Specify the class name of the association. Use it only if that name can’t be inferred from the association name. So has_one :manager will by default be linked to the Manager class, but if the real class name is Person, you’ll have to specify it with this option.

:conditions

Specify the conditions that the associated object must meet in order to be included as a WHERE SQL fragment, such as rank = 5.

:order

Specify the order in which the associated objects are returned as an ORDER BY SQL fragment, such as last_name, first_name DESC.

:dependent

If set to :destroy, the associated object is destroyed when this object is. If set to :delete, the associated object is deleted without calling its destroy method. If set to :nullify, the associated object’s foreign key is set to NULL. Also, association is assigned.

:foreign_key

Specify the foreign key used for the association. By default this is guessed to be the name of this class in lower-case and “_id” suffixed. So a Person class that makes a has_one association will use “person_id” as the default :foreign_key.

:primary_key

Specify the method that returns the primary key used for the association. By default this is id.

:include

Specify second-order associations that should be eager loaded when this object is loaded.

:as

Specifies a polymorphic interface (See belongs_to).

:select

By default, this is * as in SELECT * FROM, but can be changed if, for example, you want to do a join but not include the joined columns. Do not forget to include the primary and foreign keys, otherwise it will raise an error.

:through

Specifies a Join Model through which to perform the query. Options for :class_name and :foreign_key are ignored, as the association uses the source reflection. You can only use a :through query through a has_one or belongs_to association on the join model.

:source

Specifies the source association name used by has_one :through queries. Only use it if the name cannot be inferred from the association. has_one :favorite, :through => :favorites will look for a :favorite on Favorite, unless a :source is given.

:source_type

Specifies type of the source association used by has_one :through queries where the source association is a polymorphic belongs_to.

:readonly

If true, the associated object is readonly through the association.

:validate

If false, don’t validate the associated object when saving the parent object. false by default.

Option examples:

has_one :credit_card, :dependent => :destroy  # destroys the associated credit card
has_one :credit_card, :dependent => :nullify  # updates the associated records foreign key value to NULL rather than destroying it
has_one :last_comment, :class_name => "Comment", :order => "posted_on"
has_one :project_manager, :class_name => "Person", :conditions => "role = 'project_manager'"
has_one :attachment, :as => :attachable
has_one :boss, :readonly => :true
has_one :club, :through => :membership
has_one :primary_address, :through => :addressables, :conditions => ["addressable.primary = ?", true], :source => :addressable