sequel 3.21.0 → 3.39.0

data/doc/dataset_filtering.rdoc

@@ -4,171 +4,183 @@ Sequel is very flexibile when it comes to filtering records. You can specify you
 
 == Filtering using a custom filter string
 
-If you wish to write your SQL by hand, you can just supply it to the dataset's #filter method:
+If you wish to write your SQL by hand, you can just supply it to the dataset's #where method:
 
-  items.filter('x < 10').sql
+  items.where('x < 10').sql
   #=> "SELECT * FROM items WHERE x < 10"
 
 In order to prevent SQL injection, you can replace literal values with question marks and supply the values as additional arguments:
 
-  items.filter('category = ?', 'ruby').sql
+  items.where('category = ?', 'ruby').sql
   #=> "SELECT * FROM items WHERE category = 'ruby'"
 
 You can also use placeholders with :placeholder and a hash of placeholder values:
 
-  items.filter('category = :category', :category=>'ruby').sql
+  items.where('category = :category', :category=>'ruby').sql
   #=> "SELECT * FROM items WHERE category = 'ruby'"
 
 === Specifying SQL functions
 
-Sequel also allows you to specify functions by using the Symbol#sql_function method:
+Sequel also allows you to specify functions by using the Sequel.function method:
 
-  items.literal(:avg.sql_function(:price)) #=> "avg(price)"
+  items.literal(Sequel.function(:avg, :price)) #=> "avg(price)"
 
 If you are specifying a filter/selection/order, you can use a virtual row block:
 
   items.select{avg(price)}
 
+You can also use the {core_extensions extension}[link:files/doc/core_extensions_rdoc.html] and the +sql_function+ method:
+
+  :avg.sql_function(:price)
+
 == Filtering using a hash
 
 If you just need to compare records against values, you can supply a hash:
 
-  items.filter(:category => 'ruby').sql
+  items.where(:category => 'ruby').sql
   #=> "SELECT * FROM items WHERE (category = 'ruby')"
 
 Sequel can check for null values:
 
-  items.filter(:category => nil).sql
+  items.where(:category => nil).sql
   #=> "SELECT * FROM items WHERE (category IS NULL)"
 
 Or compare two columns:
 
-  items.filter(:x => :some_table__y).sql
+  items.where(:x => :some_table__y).sql
   #=> "SELECT * FROM items WHERE (x = some_table.y)"
 
 And also compare against multiple values:
 
-  items.filter(:category => ['ruby', 'perl']).sql
+  items.where(:category => ['ruby', 'perl']).sql
   #=> "SELECT * FROM items WHERE (category IN ('ruby', 'perl'))"
 
 Ranges (both inclusive and exclusive) can also be used:
 
-  items.filter(:price => 100..200).sql
+  items.where(:price => 100..200).sql
   #=> "SELECT * FROM items WHERE (price >= 100 AND price <= 200)"
 
-  items.filter(:price => 100...200).sql
+  items.where(: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.where(: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:
+You can pass a block to where, which is evaluated in a special context:
 
-  items.filter(:price * 2 < 50).sql
+  items.where{price * 2 < 50}.sql
   #=> "SELECT * FROM items WHERE ((price * 2) < 50) 
 
-This works for the standard inequality and arithmetic operators (though you can't use the inequality operators directly on a symbol):
+This works for the standard inequality and arithmetic operators:
 
-  items.filter(:price + 100 < 200).sql
+  items.where{price + 100 < 200}.sql
   #=> "SELECT * FROM items WHERE ((price + 100) < 200) 
 
-  items.filter(:price - 100 > 200).sql
+  items.where{price - 100 > 200}.sql
   #=> "SELECT * FROM items WHERE ((price - 100) > 200) 
 
-  items.filter(:price * 100 <= 200).sql
+  items.where{price * 100 <= 200}.sql
   #=> "SELECT * FROM items WHERE ((price * 100) <= 200) 
 
-  items.filter(:price / 100 >= 200).sql
+  items.where{price / 100 >= 200}.sql
   #=> "SELECT * FROM items WHERE ((price / 100) >= 200) 
 
 You use the overloaded bitwise and (&) and or (|) operators to combine expressions:
 
-  items.filter((:price + 100 < 200) & (:price * 100 <= 200)).sql
+  items.where{(price + 100 < 200) & (price * 100 <= 200)}.sql
   #=> "SELECT * FROM items WHERE (((price + 100) < 200) AND ((price * 100) <= 200)) 
 
-  items.filter((:price - 100 > 200) | (:price / 100 >= 200)).sql
+  items.where{(price - 100 > 200) | (price / 100 >= 200)}.sql
   #=> "SELECT * FROM items WHERE (((price - 100) > 200) OR ((price / 100) >= 200)) 
 
-To filter by equality, you use the standard hash, which can be combined with other operators:
+To filter by equality, you use the standard hash, which can be combined with other expressions using Sequel.& and Sequel.|:
 
-  items.filter({:category => 'ruby'} & (:price + 100 < 200)).sql
+  items.where{Sequel.&({:category => 'ruby'}, (price + 100 < 200))}.sql
   #=> "SELECT * FROM items WHERE ((category = 'ruby') AND ((price + 100) < 200))"
 
 This works with other hash values, such as arrays and ranges:
 
-  items.filter({:category => ['ruby', 'other']} | (:price - 100 > 200)).sql
+  items.where{Sequel.|({:category => ['ruby', 'other']}, (:price - 100 > 200))}.sql
   #=> "SELECT * FROM items WHERE ((category IN ('ruby', 'other')) OR ((price - 100) <= 200))"
 
-  items.filter({:price => (100..200)} & :active).sql
+  items.where{Sequel.&({:price => (100..200)}, :active)).sql
   #=> "SELECT * FROM items WHERE ((price >= 100 AND price <= 200) AND active)"
 
 === Negating conditions
 
-You can use the inversion operator (~) in most cases:
+You can use the exclude method to exclude conditions:
 
-  items.filter(~{:category => 'ruby'}).sql
+  items.exclude(:category => 'ruby').sql
   #=> "SELECT * FROM items WHERE (category != 'ruby')"
 
-  items.filter{~:active}.sql
+  items.exclude(:active).sql
   #=> "SELECT * FROM items WHERE NOT active"
 
-  items.filter(~(:price / 100 >= 200)).sql
+  items.exclude{price / 100 >= 200}.sql
   #=> "SELECT * FROM items WHERE ((price / 100) < 200) 
 
 === Comparing against column references
 
 You can also compare against other columns:
 
-  items.filter{credit > debit}.sql
+  items.where{credit > debit}.sql
   #=> "SELECT * FROM items WHERE (credit > debit)
 
 Or against SQL functions:
 
-  items.filter{price - 100 < max(price)}.sql
+  items.where{price - 100 < max(price)}.sql
   #=> "SELECT * FROM items WHERE ((price - 100) < max(price))"
 
 == String search functions
 
-You can search SQL strings using the #like method:
+You can search SQL strings using the Sequel.like method:
 
-  items.filter(:name.like('Acme%')).sql
+  items.where(Sequel.like(:name, 'Acme%')).sql
   #=> "SELECT * FROM items WHERE (name LIKE 'Acme%')"
 
 You can specify a Regexp as a like argument, but this will probably only work
 on PostgreSQL and MySQL:
 
-  items.filter(:name.like(/Acme.*/)).sql
+  items.where(Sequel.like(:name, /Acme.*/)).sql
   #=> "SELECT * FROM items WHERE (name ~ 'Acme.*')"
 
 Like can also take more than one argument:
 
-  items.filter(:name.like('Acme%', /Beta.*/)).sql
+  items.where(Sequel.like(:name, 'Acme%', /Beta.*/)).sql
   #=> "SELECT * FROM items WHERE ((name LIKE 'Acme%') OR (name ~ 'Beta.*'))"
 
 == String concatenation
 
-You can concatenate SQL strings using Array#sql_string_join: 
+You can concatenate SQL strings using Sequel.join: 
 
-  items.filter([:name, :comment].sql_string_join.like('%acme%')).sql
+  items.where(Sequel.join([:name, :comment]).like('%acme%')).sql
   #=> "SELECT * FROM items WHERE ((name || comment) LIKE 'Acme%')"
 
 Array#sql_string_join also takes a join argument:
 
-  items.filter([:name, :comment].sql_string_join(' ').like('%acme%')).sql
+  items.filter(Sequel.join([:name, :comment], ' ').like('%acme%')).sql
   #=> "SELECT * FROM items WHERE ((name || ' ' || comment) LIKE 'Acme%')"
 
 == Filtering using sub-queries
 
 One of the best features of Sequel is the ability to use datasets as sub-queries. Sub-queries can be very useful for filtering records, and many times provide a simpler alternative to table joins. Sub-queries can be used in all forms of filters:
 
-  refs = consumer_refs.filter(:logged_in).select(:consumer_id)
-  consumers.filter(:id => refs).sql
+  refs = consumer_refs.where(:logged_in).select(:consumer_id)
+  consumers.where(:id => refs).sql
   #=> "SELECT * FROM consumers WHERE (id IN (SELECT consumer_id FROM consumer_refs WHERE logged_in))"
 
 Note that if you are checking for the inclusion of a single column in a subselect, the subselect should only select a single column.
 
 == Using OR instead of AND
 
-By default, if you chain calls to +filter+, the conditions get ANDed together.  If you want to use an OR for a condition, you can use the +or+ method:
+By default, if you chain calls to +where+, the conditions get ANDed together.  If you want to use an OR for a condition, you can use the +or+ method:
 
-  items.filter(:name=>'Food').or(:vendor=>1).sql
+  items.where(:name=>'Food').or(:vendor=>1).sql
   #=> "SELECT * FROM items WHERE ((name = 'Food') OR (vendor = 1))"

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 in the user case, and only <tt>title=</tt>, <tt>body=</tt>, and <tt>deleted=</tt> will be allowed for mass assignment in the admin case.
+
+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.
+