sequel 3.21.0 → 3.41.0

data/doc/association_basics.rdoc

@@ -247,7 +247,7 @@ example is a tree structure:
   
   class Node
     many_to_one :parent, :class=>self
-    one_to_many :children :key=>:parent_id, :class=>self
+    one_to_many :children, :key=>:parent_id, :class=>self
   end
 
 For many_to_many self_referential associations, it's fairly similar.  Here's
@@ -293,32 +293,6 @@ Examples:
   @artist.remove_album(@album)
   @artist.remove_all_albums
 
-== Dataset Method
-
-In addition to the above methods, associations also add a instance method
-ending in +_dataset+ that returns a dataset representing the objects in the associated table:
-
-  @album.artist_id
-  # 10
-  @album.artist_dataset
-  # SELECT * FROM artists WHERE (id = 10)
-  
-  @artist.id
-  # 20
-  @artist.albums_dataset
-  # SELECT * FROM albums WHERE (artist_id = 20)
-
-The association dataset is just like any other Sequel dataset, in that
-it can be further filtered, ordered, etc.:
-
-  @artist.albums_dataset.
-   filter(:name.like('A%')).
-   order(:copies_sold).
-   limit(10)
-  # SELECT * FROM albums
-  # WHERE ((artist_id = 20) AND (name LIKE 'A%'))
-  # ORDER BY copies_sold LIMIT 10
-
 == Caching
 
 Associations are cached after being retrieved:
@@ -352,23 +326,155 @@ instance method:
   @album.artists # [<Artist ...>, ...]
   @album.associations[:artists] # [<Artist ...>, ...]
 
-Note that while the association method caches associated objects, if you
-retrieve access through the association dataset directly, the results
-will not be cached:
+== Dataset Method
+
+In addition to the above methods, associations also add a instance method
+ending in +_dataset+ that returns a dataset representing the objects in the associated table:
+
+  @album.artist_id
+  # 10
+  @album.artist_dataset
+  # SELECT * FROM artists WHERE (id = 10)
+  
+  @artist.id
+  # 20
+  @artist.albums_dataset
+  # SELECT * FROM albums WHERE (artist_id = 20)
+
+The association dataset is just like any other Sequel dataset, in that
+it can be further filtered, ordered, etc.:
+
+  @artist.albums_dataset.
+   where(Sequel.like(:name, 'A%')).
+   order(:copies_sold).
+   limit(10)
+  # SELECT * FROM albums
+  # WHERE ((artist_id = 20) AND (name LIKE 'A%'))
+  # ORDER BY copies_sold LIMIT 10
+
+Records retrieved using the +_dataset+ method are not cached in the
+associations cache.
 
   @album.artists_dataset.all # [<Artist ...>, ...]
   @album.associations[:artists] # nil
 
+== Dynamic Association Modification
+
+Similar to the +_dataset+ method, you can provide a block to the association
+method to customize the dataset that will be used to retrieve the records.  So
+you can apply a filter in either of these two ways:
+
+  @artist.albums_dataset.where(Sequel.like(:name, 'A%'))
+  @artist.albums{|ds| ds.where(Sequel.like(:name, 'A%'))}
+
+While they both apply the same filter, using the +_dataset+ method does not
+apply any of the association callbacks or handle association reciprocals (see
+below for details about callbacks and reciprocals).  Using a block instead handles
+all those things, and also caches its results in the associations cache (ignoring
+any previously cached value).
+
+== Filtering By Associations
+
+In addition to using the association method to get associated objects, you
+can also use associated objects in filters.  For example, to get
+all albums for a given artist, you would usually do:
+
+  @artist.albums
+  # or @artist.albums_dataset for a dataset
+
+You can also do the following:
+
+  Album.where(:artist=>@artist).all
+  # or leave off the .all for a dataset
+
+For filtering by a single association, this isn't very useful.  However, unlike
+using the association method, using a filter allows you to filter by multiple
+associations:
+
+  Album.where(:artist=>@artist, :publisher=>@publisher)
+
+This will return all albums by that artist and published by that publisher.
+This isn't possible using just the association method approach, though you
+can combine the approaches:
+
+  @artist.albums_dataset.where(:publisher=>@publisher)
+
+This doesn't just work for +many_to_one+ associations, it also works for
++one_to_one+, +one_to_many+, and +many_to_many+ associations:
+
+  Album.one_to_one :album_info
+  # The album related to that AlbumInfo instance
+  Album.where(:album_info=>AlbumInfo[2])
+
+  Album.one_to_many :tracks
+  # The album related to that Track instance
+  Album.where(:tracks=>Track[3])
+
+  Album.many_to_many :tags
+  # All albums related to that Tag instance
+  Album.where(:tags=>Tag[4])
+
+Note that for +one_to_many+ and +many_to_many+ associations, you still
+use the plural form even though only a single model object is given.
+
+You can also exclude by associations:
+
+  Album.exclude(:artist=>@artist).all
+  
+This will return all albums not by that artist.
+
+You can also provide an array with multiple model objects:
+
+  Album.where(:artist=>[@artist1, @artist2]).all
+
+Similar to using an array of integers or strings, this will return
+all albums whose artist is one of those two artists.  You can also
+use +exclude+ if you want all albums not by either of those artists:
+
+  Album.exclude(:artist=>[@artist1, @artist2]).all
+
+If you are using a +one_to_many+ or +many_to_many+ association, you
+may want to return records where the records matches all of multiple
+records, instead of matching any of them.  For example:
+
+  Album.where(:tags=>[@tag1, @tag2])
+  
+This matches albums that are associated with either @tag1 or @tag2 or
+both.  If you only want ones that you are associated with both, you can
+use separate filter calls:
+
+  Album.where(:tags=>@tag1).where(:tags=>@tag2)
+
+Or the the array form of condition specifiers:
+
+  Album.where([[:tags, @tag1], [:tags, @tag2]])
+
+These will return albums associated with both @tag1 and @tag2.
+
+You can also provide a dataset value when filtering by associations:
+
+  Album.where(:artist=>Artist.where(Sequel.like(:name, 'A%'))).all
+
+This will return all albums whose artist starts with 'A'. Like
+the other forms, this can be inverted:
+
+  Album.exclude(:artist=>Artist.where(Sequel.like(:name, 'A%'))).all
+ 
+This will return all albums whose artist does not start with 'A'.
+
+Note that filtering by associations only works correctly for simple
+associations (ones without conditions).
+
 == Name Collisions
 
 Because associations create instance methods, it's possible to override
-existing instance methods if you name an extension the same as an
+existing instance methods if you name an association the same as an
 existing method.  For example, <tt>values</tt> and <tt>associations</tt>
 would be bad association names.
 
 == Database Schema
 
-Creating an association, doesn't modify the database schema.  Sequel
+Creating an association doesn't modify the database schema.  Sequel
 assumes your associations reflect the existing database schema.  If not,
 you should modify your schema before creating the associations.
 
@@ -451,6 +557,8 @@ wanted to add an albums_artists join table to create the following schema:
 
 You could use the following Sequel code:
 
+  DB.create_join_table(:album_id=>:albums, :artist_id=>:artists)
+  # or
   DB.create_table(:albums_artists) do
     foreign_key :album_id, :albums
     foreign_key :artist_id, :artists
@@ -499,6 +607,19 @@ To fix this, you need to specify the full model class name using the
     end
   end
 
+If both classes are in the same module, but the default class name
+used is not correct, you need to specify the full class name with the
+:class option:
+
+  module App1
+    class AlbumArtist < Sequel::Model
+      one_to_many :albums
+    end
+    class Album < Sequel::Model
+      many_to_one :artist, :class=>"App1::AlbumArtist"
+    end
+  end
+
 == Method Details
 
 In all of these methods, _association_ is replaced by the symbol you
@@ -606,7 +727,7 @@ The <i>association</i>_dataset method returns a dataset that represents
 all associated objects.  This dataset is like any other Sequel dataset,
 in that it can be filtered, ordered, etc.:
 
-  ds = @artist.albums_dataset.filter(:name.like('A%')).order(:copies_sold)
+  ds = @artist.albums_dataset.where(Sequel.like(:name, 'A%')).order(:copies_sold)
 
 Unlike most other Sequel datasets, association datasets have a couple of
 added methods:
@@ -717,7 +838,7 @@ that returns all albums of an artist that went gold (sold at least
 500,000 copies):
 
   Artist.one_to_many :gold_albums, :class=>:Album do |ds|
-    ds.filter{copies_sold > 500000}
+    ds.where{copies_sold > 500000}
   end
 
 ==== :class
@@ -736,7 +857,7 @@ default class guessed will be wrong:
 
   # guesses GoldAlbum
   Artist.one_to_many :gold_albums do |ds|
-    ds.filter{copies_sold > 500000}
+    ds.where{copies_sold > 500000}
   end
 
 You can specify the :class option using the class itself, a Symbol,
@@ -761,13 +882,13 @@ symbol.  Defaults to :"#{self.name.underscore}_id".
 
   Artist.one_to_many :albums # :key=>:artist_id
 
-In both cases an array of symbols for a composite key association:
+In both cases an array of symbols can be used for a composite key association:
 
   Apartment.many_to_one :building # :key=>[:city, :address]
 
 ==== :conditions
 
-The conditions to use to filter the association, can be any argument passed to filter.
+The conditions to use to filter the association, can be any argument passed to +where+.
 If you use a hash or an array of two element arrays, this will also be used as a
 filter when using eager_graph to load the association.
 
@@ -800,7 +921,7 @@ columns that have the same name in both the join table and the associated
 table.  Example:
 
   Artist.one_to_many :albums, :select=>[:id, :name]
-  Album.many_to_many :tags, :select=>[:tags.*, :albums_tags__number]
+  Album.many_to_many :tags, :select=>[Sequel.expr(:tags).*, :albums_tags__number]
 
 ==== :limit
 
@@ -817,8 +938,6 @@ Use an array with two arguments for the value to specify a limit and an offset.
 This probably doesn't make a lot of sense for *_to_one associations, though you
 could use it to specify an offset.
 
-This option is ignored when eager loading.
-
 ==== :join_table [+many_to_many+]
 
 Name of table that includes the foreign keys to both the current model and the
@@ -833,7 +952,7 @@ Here's an example of the defaults:
 ==== :left_key [+many_to_many+]
 
 Foreign key in join table that points to current model's primary key, as a
-symbol.  Defaults to :"#{self.name.underscore}_id".
+symbol.  Defaults to :"#{model_name.underscore}_id".
 
   Album.many_to_many :tags # :left_key=>:album_id
 
@@ -842,9 +961,9 @@ Can use an array of symbols for a composite key association.
 ==== :right_key [+many_to_many+]
 
 Foreign key in join table that points to associated model's primary key, as a
-symbol.  Defaults to :"#{name.to_s.singularize}_id".
+symbol.  Defaults to :"#{association_name.singularize}_id".
 
-  Album.many_to_many :tags # :left_key=>:tag_id
+  Album.many_to_many :tags # :right_key=>:tag_id
   
 Can use an array of symbols for a composite key association.
 
@@ -895,7 +1014,7 @@ Here's an example of an association of songs to artists through lyrics, where
 the artist can perform any one of four tasks for the lyric:
 
   Album.one_to_many :songs, :dataset=>(proc do
-    Song.select(:songs.*).
+    Song.select_all(:songs).
      join(Lyric, :id=>:lyricid,
       id=>[:composer_id, :arranger_id, :vocalist_id, :lyricist_id])
   end)
@@ -914,8 +1033,8 @@ set up association extensions.  For more information , please see the
 ==== :primary_key
 
 The column that the :key option references, as a symbol. For +many_to_one+
-associations, this column in the associated table. For +one_to_one+ and
-+one_to_many+ associations, this column in the current table.  In both cases,
+associations, this column is in the associated table. For +one_to_one+ and
++one_to_many+ associations, this column is in the current table.  In both cases,
 it defaults to the primary key of the table. Can use an
 array of symbols for a composite key association.
 
@@ -939,7 +1058,7 @@ Column in associated table that :right_key points to, as a symbol.
 Defaults to primary key of the associated table.
 
   Tag.set_primary_key :tid
-  Album.many_to_many :tags # :left_primary_key=>:tid
+  Album.many_to_many :tags # :right_primary_key=>:tid
 
 Can use an array of symbols for a composite key association.
 
@@ -952,7 +1071,7 @@ applies to the join table.  It can be used to make sure additional columns are
 used when inserting, or that filters are used when deleting.
 
   Artist.many_to_many :lead_guitar_albums, :join_table_block=>proc do |ds|
-    ds.filter(:instrument_id=>5).set_overrides(:instrument_id=>5)
+    ds.where(:instrument_id=>5).set_overrides(:instrument_id=>5)
   end
 
 === Callback Options
@@ -1024,8 +1143,6 @@ Called after removing an object from the association:
 
 Called before the _<i>association</i>= method is called to modify the objects:
 
-Called before removing an object from the association:
-
   class Album
     # Don't associate the album with an artist if the year the album was
     # released is less than the year the artist/band started.
@@ -1049,13 +1166,12 @@ Called after the _<i>association</i>= method is called to modify the objects:
 
 ==== :after_load
 
-Called after retrieving the associated records from the database. Not called
-when eager loading via eager_graph, but called when eager loading via eager.
+Called after retrieving the associated records from the database.
 
   class Artist
     # Cache all album names to a single string when retrieving the
     # albums.
-    one_to_many :albums, :after_add=>:cache_album_names
+    one_to_many :albums, :after_load=>:cache_album_names
     
     attr_reader :album_names
     
@@ -1067,8 +1183,7 @@ when eager loading via eager_graph, but called when eager loading via eager.
   end
 
 Generally used if you know you will always want a certain action done
-when retrieving the association.  However, you need to be careful if you
-also plan on using eager_graph to eagerly load the association.
+when retrieving the association.
 
 For +one_to_many+ and +many_to_many+ associations, both the argument to
 symbol callbacks and the second argument to proc callbacks will be an
@@ -1112,13 +1227,9 @@ For many details and examples of custom eager loaders, please see the
 ==== :eager_loader_key
 
 A symbol for the key column to use to populate the key hash for the eager
-loader.  It can be necessary to specify this for custom eager loaders
-where the default key that would be used does not exist, as in that case, Sequel
-would think that the key values are all NULL, and would not attempt to
-eagerly load any associated objects for that association.  If you have a
-custom eager loader and aren't sure of a good value to use here, and you
-aren't using the key_hash (first argument to the eager_loader proc), then
-you can probably use the primary key column of the model.
+loader.  Generally does not need to be set manually, defaults to the key
+method used.  Can be set to nil to not populate the key hash (better for
+performance if a custom eager loader does not use the key_hash).
 
 ==== :eager_block
 
@@ -1137,7 +1248,7 @@ association based on dependent associations:
 
   Artist.one_to_many :albums_with_short_tracks, :class=>:Album,
    :eager_graph=>:tracks do |ds|
-    ds.filter{tracks__seconds < 120}
+    ds.where{tracks__seconds < 120}
   end
   Artist.one_to_many :albums_by_track_name, :class=>:Album,
    :eager_graph=>:tracks do |ds|
@@ -1169,13 +1280,13 @@ via eager_graph.  This is useful to specify conditions that can't be specified
 in a hash or array of two element arrays.
 
   Artist.one_to_many :gold_albums, :class=>:Album,
-    :graph_block=>proc{|j,lj,js| :copies_sold.qualify(j) > 500000}
+    :graph_block=>proc{|j,lj,js| Sequel.qualify(j, :copies_sold) > 500000}
 
 ==== :graph_join_type
 
 The type of SQL join to use when eagerly loading the association via
 eager_graph.  Defaults to :left_outer.  This is useful if you want to
-ensure that all return only artists that have albums:
+ensure that only artists that have albums are returned:
 
   Artist.one_to_many :albums, :graph_join_type=>:inner
   # Will exclude artists without an album
@@ -1201,8 +1312,8 @@ where the artist's name differs in case:
 
   Artist.one_to_many :albums, :key=>:artist_name, 
     :graph_only_conditions=>nil, 
-    :graph_block=>proc{|j,lj,js| {:lower.sql_function(artist_name.qualify(j))=>
-      :lower.sql_function(name.qualify(lj))}}
+    :graph_block=>proc{|j,lj,js| {Sequel.function(:lower, Sequel.qualify(j, :artist_name))=>
+      Sequel.function(:lower, Sequel.qualify(lj, :name))}}
 
 Note how :graph_only_conditions is set to nil to ignore any existing conditions,
 and :graph_block is used to set up the case insensitive comparison.
@@ -1218,25 +1329,46 @@ a JOIN USING or NATURAL JOIN for the graph:
   Artist.one_to_many :albums, :key=>:artist_name,
    :graph_only_conditions=>nil, :graph_join_type=>:natural
 
+==== :graph_alias_base
+
+The base name to use for the table alias when eager graphing.  Defaults to the name
+of the association.  If the alias name has already been used in the query, Sequel will create
+a unique alias by appending a numeric suffix (e.g. alias_0, alias_1, ...) until the alias is
+unique.
+
+This is mostly useful if you have associations with the same name in many models, and you want
+to be able to easily tell which table alias corresponds to which association when eagerly
+graphing multiple associations with the same name.
+
+You can override this option on a per-graph basis by specifying the association as an
+SQL::AliasedExpression instead of a symbol:
+
+  Album.eager_graph(Sequel.as(:artist, :a))
+
 ==== :eager_grapher
 
 Sets up a custom grapher to use when eager loading the objects via eager_graph.
-This is the eager_graph analogue to the :eager_loader option.
+This is the eager_graph analogue to the :eager_loader option. This isn't generally
+needed, as one of the other eager_graph related association options is usually sufficient.
 
-If specified, should be a proc that accepts three three arguments: a dataset,
-an alias to use for the table to graph for this association, and the alias that
-was used for the current table (since you can cascade associations). Should
-return a modified copy of the dataset with the association graphed into it.
+If specified, should be a proc that accepts a single hash argument, which will contain
+at least the following keys:
+
+:self :: The dataset that is doing the eager loading
+:table_alias :: An alias to use for the table to graph for this association.
+:implicit_qualifier :: The alias that was used for the current table (since you can cascade associations).
+:callback :: A callback proc used to dynamically modify the dataset to graph into the
+             current dataset, before such graphing is done. This is nil if no callback
+             proc is used.
+
+Example:
 
   Artist.one_to_many :self_title_albums, :class=>:Album,
-   :eager_grapher=>(proc do |ds, ta, iq|
-    ds.graph(Album, {:artist_id=>:id, :name=>:name},
-      :table_alias=>ta, :implicit_qualifier=>iq)
+   :eager_grapher=>(proc do |eo|
+    eo[:self].graph(Album, {:artist_id=>:id, :name=>:name},
+      :table_alias=>eo[:table_alias], :implicit_qualifier=>eo[:implicit_qualifier])
   end)
 
-This isn't generally needed, as one of the other eager_graph related
-association options is usually sufficient.
-
 ==== :order_eager_graph
 
 Whether to add the order to the dataset's order when graphing via eager_graph.
@@ -1278,7 +1410,7 @@ has received a bachelor's degree (degree starting with B):
 
   Person.many_to_many :bachelor_degree_colleges, :class=>:College,
     :join_table=>:degrees_received,
-    :graph_join_table_block=>proc{|j,lj,js| :degree.qualify(j).like('B%')}
+    :graph_join_table_block=>proc{|j,lj,js| Sequel.qualify(j, :degree).like('B%')}
 
 This should be done when graphing the join table, instead of when graphing the
 final table, as :degree is a column of the join table.
@@ -1300,6 +1432,74 @@ by the foreign/primary keys.  This option causes the
 you want to replace the default foreign/primary key conditions that Sequel
 would use when eagerly graphing.
 
+=== Column Naming Conflict Options
+
+Sequel's association support historically called methods on model objects
+to get primary key or foreign key values instead of accessing the column
+values directly, in order to allow advanced features such as associations
+based on virtual column keys.  Unfortunately, that causes issues if columns
+are used with names that clash with existing method names, which can happen
+if you want to name the association the same name as an existing column, or
+if the column has the same name as an already defined method such as
+<tt>object_id</tt>.
+
+Sequel has added the following options that allow you to work around the
+issue by either specifying the column name symbol or the method name symbol
+to use.  In most cases, these methods are designed to be used with column
+aliases defined with <tt>Model.def_column_alias</tt>:
+
+  # Example schema:
+  #  albums           artists
+  #   :id        /-->  :id
+  #   :artist --/      :name
+  #   :name
+  class Album < Sequel::Model
+    def_column_alias(:artist_id, :artist)
+    many_to_one :artist, :key=>:artist_id, :key_column=>:artist
+  end
+  
+  # Example schema:
+  #  things              objs
+  #   :id           /-->  :id
+  #   :object_id --/      :name
+  #   :name
+  class Thing < Sequel::Model
+    def_column_alias(:obj_id, :object_id)
+  end
+  class Obj < Sequel::Model
+    one_to_many :things, :key=>:object_id, :key_method=>:obj_id
+  end
+
+==== :key_column [+many_to_one+]
+
+Like the :key option, but :key references the method name, while
+:key_column references the underlying column.
+
+==== :primary_key_method [+many_to_one+]
+
+Like the :primary_key option, but :primary_key references the column
+name, while :primary_key_method references the method name.
+
+==== :primary_key_column [+one_to_many+, +one_to_one+]
+
+Like the :primary_key option, but :primary_key references the method name, while
+:primary_key_column references the underlying column.
+
+==== :key_method [+one_to_many+, +one_to_one+]
+
+Like the :key option, but :key references the column
+name, while :key_method references the method name.
+
+==== :left_primary_key_column [+many_to_many+]
+
+Like the :left_primary_key option, but :left_primary_key references the method name, while
+:left_primary_key_column references the underlying column.
+
+==== :right_primary_key_method [+many_to_many+]
+
+Like the :right_primary_key option, but :right_primary_key references the column
+name, while :right_primary_key_method references the method name.
+
 === Advanced Options
 
 ==== :reciprocal
@@ -1399,3 +1599,51 @@ associations depends on another plugin that defines instance methods of
 the same name.  In that case, the instance methods of the dependent
 plugin would override the association methods created by the main
 plugin.
+
+==== :eager_limit_strategy
+
+This setting determines what strategy to use for loading the associations
+that use the :limit setting to limit the number of returned records. You
+can't use LIMIT directly, since you want a limit for each associated
+record, not a LIMIT on the number of records returned by the dataset.
+
+By default, no strategy is used for one_to_one associations, and
+the :ruby strategy is used for *_many associations, which does a simple
+array slice after loading the associated records.  That doesn't provide
+a performance advantage, since all records are still loaded from the
+database, but it at least makes sure the cached records are accurately
+limited as they would be in the lazy load case.
+
+The reason no strategy is used by default for one_to_one associations
+is that none is needed for a true one_to_one association (since there
+is only one associated record per current record).  However, if you are
+using a one_to_one association where the relationship is really one_to_many,
+and using an order to pick the first matching row, then if you don't
+specify an :eager_limit_strategy option, you'll be loading all related
+rows just to have Sequel ignore all rows after the first.  By using a
+strategy to change the query to only return one associated record per
+current record, you can get much better database performance.
+
+You can set a value of +true+ for this option to have Sequel select what
+it thinks is the best way of limiting the records for your database.  You
+can also specify a symbol to manually choose a strategy.  The available
+strategies are:
+
+:distinct_on :: Uses DISTINCT ON to ensure only the first matching record
+                is loaded (one_to_one associations only). This is used by
+                default on PostgreSQL.
+:window_function :: Uses window functions if the database supports it.
+                    This is used by default on databases that support window
+                    functions.
+:correlated_subquery :: Uses a correlated subquery to get the information.
+                        This is never used by default as if you aren't careful,
+                        it can result in pathologically long running times.
+                        This will not work correctly for associations where
+                        the associated table has a composite primary key if
+                        the database doesn't support using IN
+                        with multiple columns.  This will also not work on MySQL
+                        because MySQL has problems using IN with a correlated
+                        subquery that contains a limit.
+:ruby :: Uses ruby array slicing to emulate database limiting (*_many
+         associations only).  This is the default if the database doesn't
+         support window functions.