belongs_to.html

<h1 id="label-.belongs_to">.belongs_to</h1>

<p>(from gem activerecord-2.3.14)</p>

<h3 id="label-Implementation+from+ActiveRecord%3A%3AAssociations%3A%3AClassMethods">Implementation from ActiveRecord::Associations::ClassMethods</h3>
<hr style="height: 1px">

<pre>belongs_to(association_id, options = {})</pre>
<hr style="height: 1px">

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

<p>Methods will be added for retrieval and query for a single associated
object, for which this object holds an id:</p>
<dl class="rdoc-list label-list"><dt>association(force_reload = false)
<dd>
<p>Returns the associated object. <code>nil</code> is returned if none is
found.</p>
</dd><dt>association=(associate)
<dd>
<p>Assigns the associate object, extracts the primary key, and sets it as the
foreign key.</p>
</dd><dt>build_association(attributes = {})
<dd>
<p>Returns a new object of the associated type that has been instantiated with
<code>attributes</code> and linked to this object through a foreign key,
but has not yet been saved.</p>
</dd><dt>create_association(attributes = {})
<dd>
<p>Returns a new object of the associated type that has been instantiated with
<code>attributes</code>, linked to this object through a foreign key, and
that has already been saved (if it passed the validation).</p>
</dd></dl>

<p>(<code>association</code> is replaced with the symbol passed as the first
argument, so <code>belongs_to :author</code> would add among others
<code>author.nil?</code>.)</p>

<h3 id="label-Example">Example</h3>

<p>A Post class declares <code>belongs_to :author</code>, which will add:</p>
<ul><li>
<p><code>Post#author</code> (similar to <code>Author.find(author_id)</code>)</p>
</li><li>
<p><code>Post#author=(author)</code> (similar to <code>post.author_id =
author.id</code>)</p>
</li><li>
<p><code>Post#author?</code> (similar to <code>post.author ==
some_author</code>)</p>
</li><li>
<p><code>Post#build_author</code> (similar to <code>post.author =
Author.new</code>)</p>
</li><li>
<p><code>Post#create_author</code> (similar to <code>post.author = Author.new;
post.author.save; post.author</code>)</p>
</li></ul>

<p>The declaration can also include an options hash to specialize the behavior
of the association.</p>

<h3 id="label-Options">Options</h3>
<dl class="rdoc-list label-list"><dt>:class_name
<dd>
<p>Specify the class name of the association. Use it only if that name can’t
be inferred from the association name. So <code>has_one :author</code> will
by default be linked to the Author class, but if the real class name is
Person, you’ll have to specify it with this option.</p>
</dd><dt>:conditions
<dd>
<p>Specify the conditions that the associated object must meet in order to be
included as a <code>WHERE</code> SQL fragment, such as <code>authorized =
1</code>.</p>
</dd><dt>:select
<dd>
<p>By default, this is <code>*</code> as in <code>SELECT * FROM</code>, 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.</p>
</dd><dt>:foreign_key
<dd>
<p>Specify the foreign key used for the association. By default this is
guessed to be the name of the association with an “_id” suffix. So a
class that defines a <code>belongs_to :person</code> association will use
“person_id” as the default <code>:foreign_key</code>. Similarly,
<code>belongs_to :favorite_person, :class_name =&gt;
&quot;Person&quot;</code> will use a foreign key of
“favorite_person_id”.</p>
</dd><dt>:primary_key
<dd>
<p>Specify the method that returns the primary key of associated object used
for the association. By default this is id.</p>
</dd><dt>:dependent
<dd>
<p>If set to <code>:destroy</code>, the associated object is destroyed when
this object is. If set to <code>:delete</code>, the associated object is
deleted <strong>without</strong> calling its destroy method. This option
should not be specified when <code>belongs_to</code> is used in conjunction
with a <code>has_many</code> relationship on another class because of the
potential to leave orphaned records behind.</p>
</dd><dt>:counter_cache
<dd>
<p>Caches the number of belonging objects on the associate class through the
use of <code>increment_counter</code> and <code>decrement_counter</code>.
The counter cache is incremented when an object of this class is created
and decremented when it’s destroyed. This requires that a column named
<code>#{table_name}_count</code> (such as <code>comments_count</code> for a
belonging Comment class) is used on the associate class (such as a Post
class). You can also specify a custom counter cache column by providing a
column name instead of a <code>true</code>/<code>false</code> value to this
option (e.g., <code>:counter_cache =&gt; :my_custom_counter</code>.) Note:
Specifying a counter cache will add it to that model’s list of readonly
attributes using <code>attr_readonly</code>.</p>
</dd><dt>:include
<dd>
<p>Specify second-order associations that should be eager loaded when this
object is loaded.</p>
</dd><dt>:polymorphic
<dd>
<p>Specify this association is a polymorphic association by passing
<code>true</code>. Note: If you’ve enabled the counter cache, then you
may want to add the counter cache attribute to the
<code>attr_readonly</code> list in the associated classes (e.g. <code>class
Post; attr_readonly :comments_count; end</code>).</p>
</dd><dt>:readonly
<dd>
<p>If true, the associated object is readonly through the association.</p>
</dd><dt>:validate
<dd>
<p>If false, don’t validate the associated objects when saving the parent
object. <code>false</code> by default.</p>
</dd><dt>:autosave
<dd>
<p>If true, always save the associated object or destroy it if marked for
destruction, when saving the parent object. Off by default.</p>
</dd><dt>:touch
<dd>
<p>If true, the associated object will be touched (the updated_at/on
attributes set to now) when this record is either saved or destroyed. If
you specify a symbol, that attribute will be updated with the current time
instead of the updated_at/on attribute.</p>
</dd></dl>

<p>Option examples:</p>

<pre class="ruby"><span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">firm</span>, :<span class="ruby-identifier">foreign_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;client_of&quot;</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">person</span>, :<span class="ruby-identifier">primary_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;name&quot;</span>, :<span class="ruby-identifier">foreign_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;person_name&quot;</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">author</span>, :<span class="ruby-identifier">class_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;Person&quot;</span>, :<span class="ruby-identifier">foreign_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;author_id&quot;</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">valid_coupon</span>, :<span class="ruby-identifier">class_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;Coupon&quot;</span>, :<span class="ruby-identifier">foreign_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;coupon_id&quot;</span>,
           :<span class="ruby-identifier">conditions</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">'discounts &gt; #{payments_count}'</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">attachable</span>, :<span class="ruby-identifier">polymorphic</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">project</span>, :<span class="ruby-identifier">readonly</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">post</span>, :<span class="ruby-identifier">counter_cache</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">company</span>, :<span class="ruby-identifier">touch</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">company</span>, :<span class="ruby-identifier">touch</span> =<span class="ruby-operator">&gt;</span> :<span class="ruby-identifier">employees_last_updated_at</span>
</pre>

<p>(from gem activerecord-2.3.14)</p>

<h3 id="label-Implementation+from+ActiveRecord%3A%3AConnectionAdapters%3A%3ATable">Implementation from ActiveRecord::ConnectionAdapters::Table</h3>
<hr style="height: 1px">

<pre>belongs_to(*args)</pre>
<hr style="height: 1px">

<p>(from gem activerecord-2.3.14)</p>

<h3 id="label-Implementation+from+ActiveRecord%3A%3AConnectionAdapters%3A%3ATableDefinition">Implementation from ActiveRecord::ConnectionAdapters::TableDefinition</h3>
<hr style="height: 1px">

<pre>belongs_to(*args)</pre>
<hr style="height: 1px">