sequel 3.37.0 → 3.38.0

data/doc/dataset_basics.rdoc

@@ -2,7 +2,7 @@
 
 == Introduction
 
-Datasets are probably the thing that separate Sequel from other database libraries.  While most database libraries have specific support for updating all records or only a single record, Sequel's ability to represent SQL queries themselves as objects is what gives Sequel most of its power.  However, if you haven't been exposed to the dataset concept before, it can be a little disorienting.  This document aims to give a basic introduction to datasets and how to use them.
+Datasets are the primary way Sequel uses to access the database. While most database libraries have specific support for updating all records or only a single record, Sequel's ability to represent SQL queries themselves as objects is what gives Sequel most of its power.  However, if you haven't been exposed to the dataset concept before, it can be a little disorienting.  This document aims to give a basic introduction to datasets and how to use them.
 
 == What a Dataset Represents
 
@@ -24,23 +24,23 @@ Here, DB represents your Sequel::Database object, and ds is your dataset, with t
 
 One of the core dataset ideas that should be understood is that datasets use a functional style of modification, in which methods called on the dataset return modified copies of the dataset, they don't modify the dataset themselves:
 
-  ds2 = ds.filter(:id=>1)
+  ds2 = ds.where(:id=>1)
   ds2
   # SELECT * FROM posts WHERE id = 1
   ds
   # SELECT * FROM posts
   
-Note how ds itself is not modified.  This is because ds.filter returns a modified copy of ds, instead of modifying ds itself.  This makes using datasets both thread safe and easy to chain:
+Note how ds itself is not modified.  This is because ds.where returns a modified copy of ds, instead of modifying ds itself.  This makes using datasets both thread safe and easy to chain:
 
   # Thread safe:
   100.times do |i|
     Thread.new do
-      ds.filter(:id=>i).first
+      ds.where(:id=>i).first
     end
   end
   
   # Easy to chain:
-  ds3 = ds.select(:id, :name).order(:name).filter{id < 100}
+  ds3 = ds.select(:id, :name).order(:name).where{id < 100}
   # SELECT id, name FROM posts WHERE id < 100 ORDER BY name
 
 Thread safety you don't really need to worry about, but chainability is core to how Sequel is generally used.  Almost all dataset methods that affect the SQL produced return modified copies of the receiving dataset.

data/doc/dataset_filtering.rdoc

@@ -4,59 +4,63 @@ 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
@@ -64,119 +68,119 @@ Ranges (both inclusive and exclusive) can also be used:
 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
+	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

@@ -25,7 +25,7 @@ To handle cases where different columns are allowed in different cases, you can
   # 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 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:
 

data/doc/migration.rdoc

@@ -523,11 +523,10 @@ The main difference between the two is that <tt>-d</tt> will use the type method
 with the database independent ruby class types, while <tt>-D</tt> will use
 the +column+ method with string types.
 
-Note that Sequel cannot dump constraints other than primary key constraints,
-so it dumps foreign key columns as plain integers.  If you are using any real
-database features such as foreign keys, constraints, or triggers, you should
-use your database's dump and restore programs instead of Sequel's schema
-dumper.
+Note that Sequel cannot dump constraints other than primary key and possibly
+foreign key constraints constraints.  If you are using database features such
+as constraints or triggers, you should use your database's dump and restore
+programs instead of Sequel's schema dumper.
 
 You can take the migration created by the schema dumper to another computer
 with an empty database, and attempt to recreate the schema using:

data/doc/model_hooks.rdoc

@@ -45,7 +45,7 @@ Sequel calls hooks in the following order when saving an existing object:
   * +before_save+
   * +around_update+
     * +before_update+
-    * INSERT QUERY
+    * UPDATE QUERY
     * +after_update+
   * +after_save+
 
@@ -89,10 +89,10 @@ Sequel does not provide a simple way to turn off the running of save/create/upda
 
 However, you should note that there are plenty of ways to modify the database without saving a model object.  One example is by using plain datasets, or one of the model's dataset methods:
 
-  Album.filter(:name=>'RF').update(:copies_sold=>:copies_sold + 1)
+  Album.where(:name=>'RF').update(:copies_sold=>:copies_sold + 1)
   # UPDATE albums SET copies_sold = copies_sold + 1 WHERE name = 'RF'
 
-In this case, the +update+ method is called on the dataset returned by <tt>Album.filter</tt>.  Even if there is only a single object with the name RF, this will not call any hooks.  If you want model hooks to be called, you need to make sure to operate on a model object:
+In this case, the +update+ method is called on the dataset returned by <tt>Album.where</tt>.  Even if there is only a single object with the name RF, this will not call any hooks.  If you want model hooks to be called, you need to make sure to operate on a model object:
 
   album = Album.first(:name=>'RF')
   album.update(:copies_sold=>album.copies_sold + 1)

data/doc/object_model.rdoc

@@ -204,6 +204,8 @@ If Sequel needs to represent an SQL concept that does not map directly to an exi
 ruby class, it will generally use a Sequel::SQL::Expression subclass to represent that
 concept.
 
+Some of the examples below show examples that require the {core_extensions extension}[link:files/doc/core_extensions_rdoc.html].
+
 === Sequel::LiteralString
 
 Sequel::LiteralString is not actually a Sequel::SQL::Expression subclass.  It is
@@ -215,7 +217,7 @@ as literal SQL code, instead of as an SQL string that needs to be escaped:
 The following shortcuts exist for creating Sequel::LiteralString objects:
 
   Sequel.lit("co'de")
-  "co'de".lit
+  "co'de".lit # core_extensions extension
 
 === Sequel::SQL::Blob
 
@@ -228,7 +230,7 @@ than SQL strings do:
 The following shortcuts exist for creating Sequel::SQL::Blob objects:
 
   Sequel.blob("blob")
-  "blob".to_sequel_blob
+  "blob".to_sequel_blob  # core_extensions extension
 
 === Sequel::SQLTime
 
@@ -256,7 +258,7 @@ where they are required.
 The following shortcuts exist for creating Sequel::SQL::ValueList objects:
 
   Sequel.value_list([[1, 2], [3, 4]])
-  [[1, 2], [3, 4]].sql_value_list
+  [[1, 2], [3, 4]].sql_value_list # core_extensions extension
 
 === Sequel::SQL::Identifier
 
@@ -268,8 +270,9 @@ automatic qualification or aliasing happens for them:
 
 The following shortcuts exist for creating Sequel::SQL::Identifier objects:
 
+  Sequel.expr(:column)
   Sequel.identifier(:col__umn)
-  :col__umn.identifier
+  :col__umn.identifier # core_extensions extension
 
 === Sequel::SQL::QualifiedIdentifier
 
@@ -279,8 +282,9 @@ Sequel::SQL::QualifiedIdentifier objects represent qualified identifiers:
 
 The following shortcuts exist for creating Sequel::SQL::QualifiedIdentifier objects:
 
+  Sequel.expr(:table__column)
   Sequel.qualify(:table, :column)
-  :column.qualify(:table)
+  :column.qualify(:table) # core_extensions extension
 
 === Sequel::SQL::AliasedExpression
 
@@ -291,8 +295,9 @@ is treated as an identifier, but the expression can be an arbitrary Sequel expre
 
 The following shortcuts exist for creating Sequel::SQL::AliasedExpression objects:
 
+  Sequel.expr(:column___alias)
   Sequel.as(:column, :alias)
-  :column.as(:alias)
+  :column.as(:alias) # core_extensions extension
   
 === Sequel::SQL::ComplexExpression
 
@@ -309,13 +314,13 @@ There are separate subclasses for representing boolean operations such as AND an
 There are many shortcuts for creating Sequel::SQL::ComplexExpression objects:
 
   Sequel.or(:col1, :col2)
-  :col1 | :col2
+  :col1 | :col2 # core_extensions extension
 
   Sequel.+(:column, 2)
-  :column + 2
+  :column + 2 # core_extensions extension
 
   Sequel.join([:column, 'b'])
-  :column + 'b'
+  :column + 'b' # core_extensions extension
 
 === Sequel::SQL::CaseExpression
 
@@ -339,8 +344,8 @@ The following shortcuts exist for creating Sequel::SQL::CaseExpression objects:
   Sequel.case({2=>1}, 0, :a)
   Sequel.case({{:a=>2}=>1}, 0)
 
-  {2=>1}.case(0, :a)
-  {{:a=>2}=>1}.case(0)
+  {2=>1}.case(0, :a) # core_extensions extension
+  {{:a=>2}=>1}.case(0) # core_extensions extension
 
 === Sequel::SQL::Cast
 
@@ -360,8 +365,8 @@ The following shortcuts exist for creating Sequel::SQL::Cast objects:
   Sequel.cast(:a, String)
   Sequel.cast(:a, :int4)
 
-  :a.cast(String)
-  :a.cast(:int4)
+  :a.cast(String) # core_extensions extension
+  :a.cast(:int4) # core_extensions extension
 
 === Sequel::SQL::ColumnAll
 
@@ -374,7 +379,8 @@ take arguments.  Still, it's possible they are still useful in some code:
 
 The following shortcut exists for creating Sequel::SQL::Cast objects:
 
-  :table.*
+  Sequel.expr(:table).*
+  :table.* # core_extensions extension
 
 === Sequel::SQL::Constant
 
@@ -399,7 +405,7 @@ name and any arguments:
 The following shortcuts exist for creating Sequel::SQL::Function objects:
 
   Sequel.function(:func, :a, 2)
-  :func.sql_function(:a, 2)
+  :func.sql_function(:a, 2) # core_extensions extension
 
 === Sequel::SQL::JoinClause
 
@@ -436,8 +442,8 @@ objects:
   Sequel.lit(':b = :v', :b=>:a, :v=>1)
   Sequel.lit(['', ' = '], :a, 1)
 
-  '? = ?'.lit(:a, 1)
-  ':b = :v'.lit(:b=>:a, :v=>1)
+  '? = ?'.lit(:a, 1) # core_extensions extension
+  ':b = :v'.lit(:b=>:a, :v=>1) # core_extensions extension
 
 === Sequel::SQL::OrderedExpression
 
@@ -461,10 +467,10 @@ The following shortcuts exist for creating Sequel::SQL::OrderedExpression object
   Sequel.asc(:a, :nulls=>:first)
   Sequel.desc(:a, :nulls=>:last)
 
-  :a.asc
-  :a.desc
-  :a.asc(:nulls=>:first)
-  :a.desc(:nulls=>:last)
+  :a.asc # core_extensions extension
+  :a.desc # core_extensions extension
+  :a.asc(:nulls=>:first) # core_extensions extension
+  :a.desc(:nulls=>:last) # core_extensions extension
 
 === Sequel::SQL::Subscript
 
@@ -479,17 +485,17 @@ The following shortcuts exist for creating Sequel::SQL::Subscript objects:
   Sequel.subscript(:a, 1)
   Sequel.subscript(:a, 1, 2)
 
-  :a.sql_subscript(1)
-  :a.sql_subscript(1, 2)
+  :a.sql_subscript(1) # core_extensions extension
+  :a.sql_subscript(1, 2) # core_extensions extension
   
 === Sequel::SQL::VirtualRow
 
 Sequel::SQL::VirtualRow is a BasicObject subclass that is the backbone behind the
 block expression support:
 
-  DB[:table].filter{a < 1}
+  DB[:table].where{a < 1}
 
-In the above code, the block is instance-evaled instead a VirtualRow instance.
+In the above code, the block is instance-evaled inside a VirtualRow instance.
 
 These objects are usually not instantiated manually.  See the
 {Virtual Row Guide}[link:files/doc/virtual_rows_rdoc.html] for details.