Module: Sequel::Model::Associations
- Included in:
- Sequel::Model
- Defined in:
- lib/sequel_model/associations.rb
Overview
Associations are used in order to specify relationships between model classes that reflect relations between tables in the database using foreign keys.
Each kind of association adds a number of methods to the model class which are specialized according to the association type and optional parameters given in the definition. Example:
class Project < Sequel::Model
belongs_to :portfolio
has_many :milestones
end
The project class now has the following methods:
-
Project#portfolio, Project#portfolio=
-
Project#milestones, Project#add_milestone, Project#remove_milestone
By default the classes for the associations are inferred from the association name, so for example the Project#portfolio will return an instance of Portfolio, and Project#milestones will return a dataset of Milestone instances, in similar fashion to how ActiveRecord infers class names.
Association definitions are also reflected by the class, e.g.:
>> Project.associations
=> [:portfolio, :milestones]
>> Project.association_reflection(:portfolio)
=> {:kind => :many_to_one, :name => :portfolio, :class_name => "Portfolio"}
The following association kinds are supported:
-
:many_to_one - Foreign key in current model’s table points to associated model’s primary key. Each associated model object can be associated with more than one current model objects. Each current model object can be associated with only one associated model object. Similar to ActiveRecord/DataMapper’s belongs_to.
-
:one_to_many - Foreign key in associated model’s table points to this model’s primary key. Each current model object can be associated with more than one associated model objects. Each associated model object can be associated with only one current model object. Similar to ActiveRecord/DataMapper’s has_many.
-
:many_to_many - A join table is used that has a foreign key that points to this model’s primary key and a foreign key that points to the associated model’s primary key. Each current model object can be associated with many associated model objects, and each associated model object can be associated with many current model objects. Similar to ActiveRecord/DataMapper’s has_and_belongs_to_many.
Associations can be defined by either using the associate method, or by calling one of the three methods: many_to_one, one_to_many, many_to_many. Sequel::Model also provides aliases for these methods that conform to ActiveRecord conventions: belongs_to, has_many, has_and_belongs_to_many. For example, the following two statements are equivalent:
associate :one_to_many, :attributes
one_to_many :attributes
Instance Method Summary collapse
-
#all_association_reflections ⇒ Object
Array of all association reflections.
-
#associate(type, name, opts = {}, &block) ⇒ Object
Associates a related model with the current model.
-
#association_reflection(name) ⇒ Object
The association reflection hash for the association of the given name.
-
#associations ⇒ Object
Array of association name symbols.
-
#many_to_many(*args, &block) ⇒ Object
(also: #has_and_belongs_to_many)
Shortcut for adding a many_to_many association, see associate.
-
#many_to_one(*args, &block) ⇒ Object
(also: #belongs_to)
Shortcut for adding a many_to_one association, see associate.
-
#one_to_many(*args, &block) ⇒ Object
(also: #has_many)
Shortcut for adding a one_to_many association, see associate.
-
#one_to_one(*args, &block) ⇒ Object
deprecated, please use many_to_one instead.
Instance Method Details
#all_association_reflections ⇒ Object
Array of all association reflections
57 58 59 |
# File 'lib/sequel_model/associations.rb', line 57 def all_association_reflections association_reflections.values end |
#associate(type, name, opts = {}, &block) ⇒ Object
Associates a related model with the current model. The following types are supported:
-
:many_to_one - Foreign key in current model’s table points to associated model’s primary key. Each associated model object can be associated with more than one current model objects. Each current model object can be associated with only one associated model object. Similar to ActiveRecord/DataMapper’s belongs_to.
-
:one_to_many - Foreign key in associated model’s table points to this model’s primary key. Each current model object can be associated with more than one associated model objects. Each associated model object can be associated with only one current model object. Similar to ActiveRecord/DataMapper’s has_many.
-
:many_to_many - A join table is used that has a foreign key that points to this model’s primary key and a foreign key that points to the associated model’s primary key. Each current model object can be associated with many associated model objects, and each associated model object can be associated with many current model objects. Similar to ActiveRecord/DataMapper’s has_and_belongs_to_many.
The following options can be supplied:
-
*ALL types*:
-
:class_name - The name of the associated class as a string. If not given, uses the association’s name, which is camelized (and singularized if type is :one,many_to_many)
-
:class - The associated class itself. Simpler than using :class_name, but can’t be used always due to dependencies not being loaded.
-
-
:many_to_one:
-
:key - foreign_key in current model’s table that references associated model’s primary key, as a symbol. Defaults to :“#name_id”.
-
-
:one_to_many:
-
:key - foreign key in associated model’s table that references current model’s primary key, as a symbol. Defaults to :“#Sequel::Model::Associations.selfself.nameself.name.underscore_id”.
-
:order - the column by which to order the association dataset.
-
:cache - set to true to cache and return an array of objects instead of a dataset.
-
-
:many_to_many:
-
:join_table - name of table that includes the foreign keys to both the current model and the associated model, as a symbol. Defaults to the name of current model and name of associated model, pluralized, underscored, sorted, and joined with ‘_’.
-
:left_key - foreign key in join table that points to current model’s primary key, as a symbol.
-
:right_key - foreign key in join table that points to associated model’s primary key, as a symbol.
-
:order - the column by which to order the association dataset.
-
:cache - set to true to cache and return an array of objects instead of a dataset.
-
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 |
# File 'lib/sequel_model/associations.rb', line 109 def associate(type, name, opts = {}, &block) # check arguments raise ArgumentError unless [:many_to_one, :one_to_many, :many_to_many].include?(type) && Symbol === name # deprecation if opts[:from] STDERR << "The :from option is deprecated, please use the :class option instead.\r\n" opts[:class] = opts[:from] end # prepare options opts[:class_name] ||= opts[:class].name if opts[:class] opts = association_reflections[name] = opts.merge(:type => type, :name => name, :block => block) send(:"def_#{type}", name, opts) end |
#association_reflection(name) ⇒ Object
The association reflection hash for the association of the given name.
127 128 129 |
# File 'lib/sequel_model/associations.rb', line 127 def association_reflection(name) association_reflections[name] end |
#associations ⇒ Object
Array of association name symbols
132 133 134 |
# File 'lib/sequel_model/associations.rb', line 132 def associations association_reflections.keys end |
#many_to_many(*args, &block) ⇒ Object Also known as: has_and_belongs_to_many
Shortcut for adding a many_to_many association, see associate
155 156 157 |
# File 'lib/sequel_model/associations.rb', line 155 def many_to_many(*args, &block) associate(:many_to_many, *args, &block) end |
#many_to_one(*args, &block) ⇒ Object Also known as: belongs_to
Shortcut for adding a many_to_one association, see associate
137 138 139 |
# File 'lib/sequel_model/associations.rb', line 137 def many_to_one(*args, &block) associate(:many_to_one, *args, &block) end |
#one_to_many(*args, &block) ⇒ Object Also known as: has_many
Shortcut for adding a one_to_many association, see associate
143 144 145 |
# File 'lib/sequel_model/associations.rb', line 143 def one_to_many(*args, &block) associate(:one_to_many, *args, &block) end |
#one_to_one(*args, &block) ⇒ Object
deprecated, please use many_to_one instead
149 150 151 152 |
# File 'lib/sequel_model/associations.rb', line 149 def one_to_one(*args, &block) STDERR << "one_to_one relation definitions are deprecated, please use many_to_one instead.\r\n" many_to_one(*args, &block) end |