has_many

Specifies a one-to-many association. The following methods for retrieval and query of collections of associated objects will be added:

collection(force_reload = false)

Returns an array of all the associated objects. An empty array is returned if none are found.

collection<<(object, â¦)

Adds one or more objects to the collection by setting their foreign keys to the collection's primary key. Note that this operation instantly fires update SQL without waiting for the save or update call on the parent object, unless the parent object is a new record.

collection.delete(object, â¦)

Removes one or more objects from the collection by setting their foreign keys to NULL. Objects will be in addition destroyed if they're associated with dependent: :destroy, and deleted if they're associated with dependent: :delete_all.

If the :through option is used, then the join records are deleted (rather than nullified) by default, but you can specify dependent: :destroy or dependent: :nullify to override this.

collection.destroy(object, â¦)

Removes one or more objects from the collection by running destroy on each record, regardless of any dependent option, ensuring callbacks are run.

If the :through option is used, then the join records are destroyed instead, not the objects themselves.

collection=objects

Replaces the collections content by deleting and adding objects as appropriate. If the :through option is true callbacks in the join models are triggered except destroy callbacks, since deletion is direct.

collection_singular_ids

Returns an array of the associated objects' ids

collection_singular_ids=ids

Replace the collection with the objects identified by the primary keys in ids. This method loads the models and calls collection=. See above.

collection.clear

Removes every object from the collection. This destroys the associated objects if they are associated with dependent: :destroy, deletes them directly from the database if dependent: :delete_all, otherwise sets their foreign keys to NULL. If the :through option is true no destroy callbacks are invoked on the join models. Join models are directly deleted.

collection.empty?

Returns true if there are no associated objects.

collection.size

Returns the number of associated objects.

collection.find(â¦)

Finds an associated object according to the same rules as ActiveRecord::Base.find.

collection.exists?(â¦)

Checks whether an associated object with the given conditions exists. Uses the same rules as ActiveRecord::Base.exists?.

collection.build(attributes = {}, â¦)

Returns one or more new objects of the collection type that have been instantiated with attributes and linked to this object through a foreign key, but have not yet been saved.

collection.create(attributes = {})

Returns a new object of the collection 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). Note: This only works if the base model already exists in the DB, not if it is a new (unsaved) record!

collection.create!(attributes = {})

Does the same as collection.create, but raises ActiveRecord::RecordInvalid if the record is invalid.

(Note: collection is replaced with the symbol passed as the first argument, so has_many :clients would add among others clients.empty?.)

Example

A Firm class declares has_many :clients, which will add:

• Firm#clients (similar to Client.where(firm_id: id))

• Firm#clients<<

• Firm#clients.delete

• Firm#clients.destroy

• Firm#clients=

• Firm#client_ids

• Firm#client_ids=

• Firm#clients.clear

• Firm#clients.empty? (similar to firm.clients.size == 0)

• Firm#clients.size (similar to Client.count "firm_id = #{id}")

• Firm#clients.find (similar to Client.where(firm_id: id).find(id))

• Firm#clients.exists?(name: 'ACME') (similar to Client.exists?(name: 'ACME', firm_id: firm.id))

• Firm#clients.build (similar to Client.new("firm_id" => id))

• Firm#clients.create (similar to c = Client.new("firm_id" => id); c.save; c)

• Firm#clients.create! (similar to c = Client.new("firm_id" => id); c.save!)

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

Options

: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_many :products will by default be linked to the Product class, but if the real class name is SpecialProduct, you'll have to specify it with this option.

: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_many 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.

:dependent

Controls what happens to the associated objects when their owner is destroyed. Note that these are implemented as callbacks, and Rails executes callbacks in order. Therefore, other similar callbacks may affect the :dependent behavior, and the :dependent behavior may affect other callbacks.

• :destroy causes all the associated objects to also be destroyed.

• :delete_all causes all the associated objects to be deleted directly from the database (so callbacks will not be executed).

• :nullify causes the foreign keys to be set to NULL. Callbacks are not executed.

• :restrict_with_exception causes an exception to be raised if there are any associated records.

• :restrict_with_error causes an error to be added to the owner if there are any associated objects.

If using with the :through option, the association on the join model must be a belongs_to, and the records which get deleted are the join records, rather than the associated records.

:counter_cache

This option can be used to configure a custom named :counter_cache. You only need this option, when you customized the name of your :counter_cache on the belongs_to association.

:as

Specifies a polymorphic interface (See belongs_to).

:through

Specifies an association through which to perform the query. This can be any other type of association, including other :through associations. Options for :class_name, :primary_key and :foreign_key are ignored, as the association uses the source reflection.

If the association on the join model is a belongs_to, the collection can be modified and the records on the :through model will be automatically created and removed as appropriate. Otherwise, the collection is read-only, so you should manipulate the :through association directly.

If you are going to modify the association (rather than just read from it), then it is a good idea to set the :inverse_of option on the source association on the join model. This allows associated records to be built which will automatically create the appropriate join model records when they are saved. (See the 'Association Join Models' section above.)

:source

Specifies the source association name used by has_many :through queries. Only use it if the name cannot be inferred from the association. has_many :subscribers, through: :subscriptions will look for either :subscribers or :subscriber on Subscription, unless a :source is given.

:source_type

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

:validate

If false, don't validate the associated objects when saving the parent object. true by default.

:autosave

If true, always save the associated objects or destroy them if marked for destruction, when saving the parent object. If false, never save or destroy the associated objects. By default, only save associated objects that are new records. This option is implemented as a before_save callback. Because callbacks are run in the order they are defined, associated objects may need to be explicitly saved in any user-defined before_save callbacks.

Note that accepts_nested_attributes_for sets :autosave to true.

:inverse_of

Specifies the name of the belongs_to association on the associated object that is the inverse of this has_many association. Does not work in combination with :through or :as options. See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.

Option examples:

has_many :comments, -> { order "posted_on" }
has_many :comments, -> { includes :author }
has_many :people, -> { where("deleted = 0").order("name") }, class_name: "Person"
has_many :tracks, -> { order "position" }, dependent: :destroy
has_many :comments, dependent: :nullify
has_many :tags, as: :taggable
has_many :reports, -> { readonly }
has_many :subscribers, through: :subscriptions, source: :user