sequel 3.21.0 → 3.36.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,13 +326,150 @@ 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.
+   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
+
+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.filter(:name.like('A%'))
+  @artist.albums{|ds| ds.filter(:name.like('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).
+
+Note that if you are using ruby 1.8.6, you can't pass a block to the association
+method, you have to pass a proc as an argument:
+
+  @artist.albums(proc{|ds| ds.filter(:name.like('A%'))})
+
+== 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.filter(: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.filter(: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.filter(: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.filter(:album_info=>AlbumInfo[2])
+
+  Album.one_to_many :tracks
+  # The album related to that Track instance
+  Album.filter(:tracks=>Track[3])
+
+  Album.many_to_many :tags
+  # All albums related to that Tag instance
+  Album.filter(: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.filter(: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.filter(: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.filter(:tags=>@tag1).filter(:tags=>@tag2)
+
+Or the the array form of condition specifiers:
+
+  Album.filter([[: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.filter(:artist=>Artist.filter(:name.like('A%'))).all
+
+This will return all albums whose artist starts with 'A'. Like
+the other forms, this can be inverted:
+
+  Album.exclude(:artist=>Artist.filter(:name.like('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
@@ -368,7 +479,7 @@ 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.
 
@@ -1055,7 +1166,7 @@ when eager loading via eager_graph, but called when eager loading via eager.
   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
     
@@ -1218,25 +1329,44 @@ 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.
+
 ==== :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 one or three three arguments.
+If the proc takes one argument, it will be given a hash with the following keys:
 
-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.
+: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.
+
+If the proc takes three arguments, it gets passed the :self, :association_alias,
+and :table_alias values. The 3 argument procs are allowed for backwards
+compatibility, and it is recommended to use the 1 argument proc format
+for new code.
 
   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.
@@ -1300,6 +1430,78 @@ 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
+    many_to_one :things, :key=>:object_id, :key_method=>:obj_id
+  end
+
+Note that for eager loading purposes, you generally need to set the
+<tt>:eager_loader_key</tt> option as well, specifying the underlying
+column(s) to use.
+
+==== :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 +1601,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.

data/doc/dataset_basics.rdoc

@@ -74,12 +74,12 @@ Most Dataset methods that users will use can be broken down into two types:
 
 Most dataset methods fall into this category, which can be further broken down by the clause they affect:
 
-SELECT:: select, select_all, select_append, select_more
+SELECT:: select, select_all, select_append, select_group, select_more
 FROM:: from, from_self
 JOIN:: join, left_join, right_join, full_join, natural_join, natural_left_join, natural_right_join, natural_full_join, cross_join, inner_join, left_outer_join, right_outer_join, full_outer_join, join_table
-WHERE:: where, filter, exclude, and, or, grep, invert, unfiltered
-GROUP:: group, group_by, group_and_count, ungrouped
-HAVING:: having, filter, exclude, and, or, grep, invert, unfiltered
+WHERE:: where, filter, exclude, exclude_where, and, or, grep, invert, unfiltered
+GROUP:: group, group_by, group_and_count, select_group, ungrouped
+HAVING:: having, filter, exclude, exclude_having, and, or, grep, invert, unfiltered
 ORDER:: order, order_by, order_append, order_prepend, order_more, reverse, reverse_order, unordered
 LIMIT:: limit, unlimited
 compounds:: union, intersect, except
@@ -93,7 +93,7 @@ other:: clone, distinct, naked, server, with_sql
 
 Most other dataset methods commonly used will execute the dataset's SQL on the database:
 
-SELECT (All Records):: all, each, map, to_hash, select_map, select_order_map, select_hash, to_csv
+SELECT (All Records):: all, each, map, to_hash, to_hash_groups, select_map, select_order_map, select_hash, select_hash_groups, to_csv
 SELECT (First Record):: first, last, get, []
 SELECT (Aggregates):: count, avg, max, min, sum, range, interval
 INSERT:: insert, <<, import, multi_insert, insert_multiple

data/doc/dataset_filtering.rdoc

@@ -59,6 +59,14 @@ Ranges (both inclusive and exclusive) can also be used:
   items.filter(:price => 100...200).sql
   #=> "SELECT * FROM items WHERE (price >= 100 AND price < 200)"
 
+== Filtering using an array
+
+If you need to select multiple items from a dataset, you can supply an array:
+
+	item_array = [1, 38, 47, 99]
+	items.filter(:id => item_array).sql
+	#=> "SELECT * FROM items WHERE (id IN (1, 38, 47, 99))"
+
 == Filtering using expressions
 
 Sequel allows you to use ruby expressions directly in the call to filter:

data/doc/mass_assignment.rdoc

@@ -0,0 +1,56 @@
+= Sequel::Model Mass Assignment
+
+Most Model methods that take a hash of attribute keys and values, including <tt>Model.new</tt>, <tt>Model.create</tt>, <tt>Model#set</tt> and <tt>Model#update</tt> are subject to Sequel's mass assignment rules.
+When you pass a hash to these methods, each key has an <tt>=</tt> appended to it (the setter method), and if the setter method exists and access to it is not restricted, Sequel will call the setter method with the hash value.
+By default, there are two types of setter methods that are restricted.  
+The first is methods like <tt>typecast_on_assignment=</tt> and <tt>==</tt>, which don't affect columns.
+These methods cannot be enabled for mass assignment.
+The second is primary key setters.
+To enable use of primary key setters, you need to call +unrestrict_primary_key+ for that model:
+
+  Post.unrestrict_primary_key
+
+Since mass assignment by default allows modification of all column values except for primary key columns, it can be a security risk in some cases.
+Sequel has multiple ways of securing mass assignment.
+The first way is using +set_allowed_columns+:
+
+  Post.set_allowed_columns :title, :body, :category
+
+This explicitly sets which methods are allowed (<tt>title=</tt>, <tt>body=</tt>, and <tt>category=</tt>), all other methods will not be allowed.
+This method is useful in simple applications where the same columns are allowed in all cases, but not appropriate when different columns are allowed in different scenarios (e.g. admin access vs. user access).
+To handle cases where different columns are allowed in different cases, you can use +set_only+ or +update_only+:
+
+  # user case
+  post.set_only(params[:post], :title, :body)
+  # admin case
+  post.set_only(params[:post], :title, :body, :deleted)
+
+In this case, only the <tt>title=</tt> and <tt>body=</tt> methods will be allowed in the mass assignment.
+
+By default, if an invalid setter method call is attempted, Sequel raises a <tt>Sequel::Error</tt> exception.  You can have Sequel silently ignore invalid calls by doing:
+
+  # Global default
+  Sequel::Model.strict_param_setting = false
+  # Class level
+  Post.strict_param_setting = false
+  # Instance level
+  post.strict_param_setting = false
+
+These mass assignment methods have been around a long time, but starting in Sequel 3.12.0, the +set_fields+ and +update_fields+ methods were added, and these may be a better mass assignment choice for most users.
+These methods take two arguments, the attributes hash as the first argument, and a single array of valid field names as the second argument:
+
+  post.set_fields(params[:post], [:title, :body])
+
++set_fields+ and +update_fields+ differ in implementation from +set_only+ and +update_only+.
+With +set_only+ and +update_only+, the hash is iterated over and it checks each method call attempt to see if it is valid.
+With +set_fields+ and +update_fields+, the array is iterated over, and it just looks up the value in the hash and calls the appropriate setter method.
+
++set_fields+ and +update_fields+ are designed for the case where you are expecting specific fields in the input, and want to ignore the other fields.
+They work great for things like HTML forms where the form fields are static.
++set_only+ and +update_only+ are designed for cases where you are not sure what fields are going to be present in the input, but still want to make sure only certain setter methods can be called.
+They work great for flexible APIs.
+
+Starting in Sequel 3.34.0, +set_fields+ and +update_fields+ take an optional argument hash, and currently handles the :missing option.  With <tt>:missing=>:skip</tt>, +set_fields+ and +update_fields+ will just skip missing entries in the hash, allowing them to be used in flexible APIs.  With <tt>:missing=>:raise</tt>, +set_fields+ and +update_fields+ will raise an error if one of the entries in the hash is missing, instead of just assigning the value to nil or whatever the hash's default value is.  That allows stricter checks, similar to the :strict_param_checking setting for the default mass assignment methods.
+
+In all of the mass assignment cases, methods starting with +set+ will set the attributes without saving the object, while methods starting with +update+ will set the attributes and then save the changes to the object.
+