sequel 3.12.1 → 3.13.0

data/doc/association_basics.rdoc

@@ -295,8 +295,8 @@ Examples:
 
 == Dataset Method
 
-In addition to the above methods, associations also add a dataset method
-that returns a dataset representing the objects in the associated table:
+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
@@ -1386,3 +1386,16 @@ a one_to_one association that can actually return more than one row
 a many_to_many association where there is a unique index in the join table
 so that you know only one object will ever be associated through the
 association.
+
+==== :methods_module
+
+The module that the methods created by the association will be placed
+into.  Defaults to the module containing the model's columns.  This
+is not included in the model's class, so you are responsible for doing
+that manually.
+
+This is only useful in rare cases, such as when a plugin that adds
+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.

data/doc/cheat_sheet.rdoc

@@ -48,8 +48,8 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 == Retrieve rows
 
   dataset.each{|r| p r}
-  dataset.all #=> [{...}, {...}, ...]
-  dataset.first
+  dataset.all # => [{...}, {...}, ...]
+  dataset.first # => {...}
 
 == Update/Delete rows
 
@@ -66,47 +66,51 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 == Filtering (see also doc/dataset_filtering.rdoc)
 
+=== Equality
+
   dataset.filter(:name => 'abc')
   dataset.filter('name = ?', 'abc')
 
-  dataset.filter{|o| o.value > 100}
-  dataset.exclude{|o| o.value <= 100}
+=== Inequality
+
+  dataset.filter{value > 100}
+  dataset.exclude{value <= 100}
+
+=== Inclusion
 
   dataset.filter(:value => 50..100)
-  dataset.where{|o| (o.value >= 50) & (o.value <= 100)}
+  dataset.where{(value >= 50) & (value <= 100)}
 
   dataset.where('value IN ?', [50,75,100])
   dataset.where(:value=>[50,75,100])
 
-  dataset.filter(:name => 'abc').first
-  dataset[:name => 'abc']
+  dataset.where(:id=>other_dataset.select(:other_id))
 
-  dataset.where('price > (SELECT avg(price) + 100 FROM table)')
-  dataset.filter{|o| o.price > dataset.select(o.avg(price) + 100)}
+=== Subselects as scalar values
 
-=== Advanced filtering using ruby expressions
+  dataset.where('price > (SELECT avg(price) + 100 FROM table)')
+  dataset.filter{price > dataset.select(avg(price) + 100)}
 
-  DB[:items].filter{|o| o.price < 100}.sql 
-  #=> "SELECT * FROM items WHERE (price < 100)" 
+=== LIKE/Regexp
 
-  DB[:items].filter(:name.like('AL%')).sql 
-  #=> "SELECT * FROM items WHERE (name LIKE 'AL%')" 
+  DB[:items].filter(:name.like('AL%'))
+  DB[:items].filter(:name => /^AL/)
 
-There's support for nested expressions with AND, OR and NOT:
+=== AND/OR/NOT
 
-  DB[:items].filter{|o| (o.x > 5) & (o.y > 10)}.sql 
-  #=> "SELECT * FROM items WHERE ((x > 5) AND (y > 10))" 
+  DB[:items].filter{(x > 5) & (y > 10)}.sql 
+  # SELECT * FROM items WHERE ((x > 5) AND (y > 10))
 
   DB[:items].filter({:x => 1, :y => 2}.sql_or & ~{:z => 3}).sql 
-  #=> "SELECT * FROM items WHERE (((x = 1) OR (y = 2)) AND (z != 3))"
+  # SELECT * FROM items WHERE (((x = 1) OR (y = 2)) AND (z != 3))
 
-You can use arithmetic operators and specify SQL functions:
+=== Mathematical operators
 
   DB[:items].filter((:x + :y) > :z).sql 
-  #=> "SELECT * FROM items WHERE ((x + y) > z)" 
+  # SELECT * FROM items WHERE ((x + y) > z)
 
-  DB[:items].filter{|o| :price - 100 < o.avg(:price)}.sql 
-  #=> "SELECT * FROM items WHERE ((price - 100) < avg(price))" 
+  DB[:items].filter{price - 100 < avg(price)}.sql 
+  # SELECT * FROM items WHERE ((price - 100) < avg(price))
 
 == Ordering
 
@@ -114,7 +118,7 @@ You can use arithmetic operators and specify SQL functions:
   dataset.reverse_order(:kind)
   dataset.order(:kind.desc, :name)
 
-== Row ranges
+== Limit/Offset
 
   dataset.limit(30) # LIMIT 30
   dataset.limit(30, 10) # LIMIT 30 OFFSET 10
@@ -122,12 +126,12 @@ You can use arithmetic operators and specify SQL functions:
 == Joins
 
   DB[:items].left_outer_join(:categories, :id => :category_id).sql 
-  #=> "SELECT * FROM items LEFT OUTER JOIN categories ON categories.id = items.category_id"
+  # SELECT * FROM items LEFT OUTER JOIN categories ON categories.id = items.category_id
 
   DB[:items].join(:categories, :id => :category_id).join(:groups, :id => :items__group_id) 
-  #=> "SELECT * FROM items INNER JOIN categories ON categories.id = items.category_id INNER JOIN groups ON groups.id = items.group_id"
+  # SELECT * FROM items INNER JOIN categories ON categories.id = items.category_id INNER JOIN groups ON groups.id = items.group_id
 	
-== Summarizing
+== Aggregate functions methods
 
   dataset.count #=> record count
   dataset.max(:price)
@@ -135,6 +139,7 @@ You can use arithmetic operators and specify SQL functions:
   dataset.avg(:price)
   dataset.sum(:stock)
 
+  dataset.group_and_count(:category)
   dataset.group(:category).select(:category, :AVG.sql_function(:price))
 
 == SQL Functions / Literals
@@ -150,11 +155,11 @@ You can use arithmetic operators and specify SQL functions:
   DB.create_table :items do
     primary_key :id
     String :name, :unique => true, :null => false
-    boolean :active, :default => true
+    TrueClass :active, :default => true
     foreign_key :category_id, :categories
-    Time :created_at
+    DateTime :created_at
     
-    index :grade
+    index :created_at
   end
 
   DB.drop_table :items
@@ -169,7 +174,7 @@ You can use arithmetic operators and specify SQL functions:
   DB[:items].select(:name.as(:item_name))
   DB[:items].select(:name___item_name)
   DB[:items___items_table].select(:items_table__name___item_name)
-  # => "SELECT items_table.name AS item_name FROM items AS items_table"
+  # SELECT items_table.name AS item_name FROM items AS items_table
 
 == Transactions
 
@@ -211,8 +216,8 @@ Savepoints can be used if the database supports it:
 
 == Miscellaneous:
 
-  dataset.sql #=> "SELECT * FROM items"
-  dataset.delete_sql #=> "DELETE FROM items"
-  dataset.where(:name => 'sequel').exists #=> "EXISTS ( SELECT * FROM items WHERE name = 'sequel' )"
+  dataset.sql # "SELECT * FROM items"
+  dataset.delete_sql # "DELETE FROM items"
+  dataset.where(:name => 'sequel').exists # "EXISTS ( SELECT * FROM items WHERE name = 'sequel' )"
   dataset.columns #=> array of columns in the result set, does a SELECT
   DB.schema(:items) => [[:id, {:type=>:integer, ...}], [:name, {:type=>:string, ...}], ...]

data/doc/dataset_filtering.rdoc

@@ -1,6 +1,6 @@
 = Dataset Filtering 
 
-Sequel offers unparalleled flexibility when it comes to filtering records. You can specify your conditions as a custom string, as a string with parameters, as a hash of values to compare against, or as ruby code that Sequel translates into SQL expressions.
+Sequel is very flexibile when it comes to filtering records. You can specify your conditions as a custom string, as a string with parameters, as a hash of values to compare against, or as ruby code that Sequel translates into SQL expressions.
 
 == Filtering using a custom filter string
 
@@ -14,12 +14,21 @@ In order to prevent SQL injection, you can replace literal values with question
   items.filter('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
+  #=> "SELECT * FROM items WHERE category = 'ruby'"
+
 === Specifying SQL functions
 
-Sequel also allows you to specify functions by using the Symbol#sql_function method (and the Symbol#[] method on ruby 1.8):
+Sequel also allows you to specify functions by using the Symbol#sql_function method:
 
   items.literal(:avg.sql_function(:price)) #=> "avg(price)"
 
+If you are specifying a filter/selection/order, you can use a virtual row block:
+
+  items.select{avg(price)}
+
 == Filtering using a hash
 
 If you just need to compare records against values, you can supply a hash:
@@ -57,7 +66,7 @@ Sequel allows you to use ruby expressions directly in the call to filter:
   items.filter(: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 in ruby 1.9):
+This works for the standard inequality and arithmetic operators (though you can't use the inequality operators directly on a symbol):
 
   items.filter(:price + 100 < 200).sql
   #=> "SELECT * FROM items WHERE ((price + 100) < 200) 
@@ -94,7 +103,7 @@ This works with other hash values, such as arrays and ranges:
 
 === Negating conditions
 
-You can use the negation operator (~) in most cases:
+You can use the inversion operator (~) in most cases:
 
   items.filter(~{:category => 'ruby'}).sql
   #=> "SELECT * FROM items WHERE (category != 'ruby')"
@@ -109,12 +118,12 @@ You can use the negation operator (~) in most cases:
 
 You can also compare against other columns:
 
-  items.filter{|o| o.credit > :debit}.sql
+  items.filter{credit > debit}.sql
   #=> "SELECT * FROM items WHERE (credit > debit)
 
 Or against SQL functions:
 
-  items.filter{|o| :price - 100 < o.max(:price)}.sql
+  items.filter{price - 100 < max(price)}.sql
   #=> "SELECT * FROM items WHERE ((price - 100) < max(price))"
 
 == String search functions
@@ -155,4 +164,4 @@ One of the best features of Sequel is the ability to use datasets as sub-queries
   consumers.filter(:id => refs).sql
   #=> "SELECT * FROM consumers WHERE (id IN (SELECT consumer_id FROM consumer_refs WHERE logged_in))"
 
-Note that if you compare against a sub-query, you must select a single column in the sub-query.
+Note that if you are checking for the inclusion of a single column in a subselect, the subselect should only select a single column.

data/doc/prepared_statements.rdoc

@@ -8,7 +8,7 @@ the following databases:
 * PostgreSQL (using the pg driver, requires type specifiers)
 * MySQL (prepared statements only, as the ruby mysql driver doesn't support
   bound variables)
-* SQLite (a new native prepared statement is used for each call, though)
+* SQLite
 * JDBC
 
 Support on other databases is emulated via string interpolation.
@@ -31,7 +31,7 @@ Using bound variables for this query is simple:
   ds.call(:select, :n=>'Jim')
 
 This will do the equivalent of selecting records that have the name 'Jim'. It
-returns all records, and can take a block that is passed to Dataset#all.
+returns all records, and can take a block that is passed to <tt>Dataset#all</tt>.
 
 Deleting or returning the first record works similarly:
 
@@ -49,16 +49,16 @@ may itself contain placeholders:
 == Prepared Statements
 
 Prepared statement support is similar to bound variable support, but you
-use Dataset#prepare with a name, and Dataset#call or Database#call later with the values:
+use <tt>Dataset#prepare</tt> with a name, and <tt>Dataset#call</tt> or <tt>Database#call</tt> later with the values:
 
   ds = DB[:items].filter(:name=>:$n)
   ps = ds.prepare(:select, :select_by_name)
   ps.call(:n=>'Jim')
   DB.call(:select_by_name, :n=>'Jim') # same as above
 
-The Dataset#prepare method returns a prepared statement, and also stores a
+The <tt>Dataset#prepare</tt> method returns a prepared statement, and also stores a
 copy of the prepared statement in the database for later use.  For insert
-and update queries, the hash to insert/update is passed to prepare:
+and update queries, the hash to insert/update is passed to +prepare+:
 
   ps1 = DB[:items].prepare(:insert, :insert_with_name, :name=>:$n)
   ps1.call(:n=>'Jim')
@@ -82,8 +82,8 @@ in the SQL).  Prepared statements are always server side.
 
 === SQLite
 
-SQLite supports bound variables and prepared statements exactly the same, since
-a new native prepared statement is created and executed for each call.
+SQLite supports both prepared statements and bound variables.  Prepared
+statements are cached per connection.
 
 === MySQL
 

data/doc/querying.rdoc

@@ -92,7 +92,7 @@ in the dataset unless you give the dataset an unambiguous order.
 
 ==== Retrieving a Single Column Value
 
-Sometimes, intead of wanting an entire row, you only want the value of
+Sometimes, instead of wanting an entire row, you only want the value of
 a specific column.  For this <tt>Sequel::Dataset#get</tt> is the method
 you want:
 
@@ -102,7 +102,7 @@ you want:
 
 === Retrieving Multiple Objects
 
-==== As a Array of Hashes or Model Objects
+==== As an Array of Hashes or Model Objects
 
 In many cases, you want an array of all of the rows associated with the
 dataset, in which case <tt>Sequel::Dataset#all</tt> is the method you
@@ -141,7 +141,7 @@ given column.  So the previous example can be handled more easily with:
   # SELECT * FROM artists
   => ["YJM", "AS"]
 
-One difference between these two ways of return an array of values is
+One difference between these two ways of returning an array of values is
 that providing +map+ with an argument is really doing:
 
   artist_names = Artist.map{|x| x[:name]} # not x.name
@@ -172,7 +172,8 @@ using the +to_hash+ method:
   => {"YJM"=>1, "AS"=>2}
 
 As you can see, the +to_hash+ method uses the first symbol as the key
-and the second symbol as the value.  So if you swap the two arguments:
+and the second symbol as the value.  So if you swap the two arguments the hash
+will have its keys and values transposed:
 
   artist_names = Artist.to_hash(:id, :name)
   # SELECT * FROM artists

data/doc/release_notes/3.13.0.txt

@@ -0,0 +1,210 @@
+= New Plugins
+
+* A json_serializer plugin was added that allows you to serialize
+  model instances or datasets to JSON using to_json.  It requires
+  the json library.  The API was modeled on ActiveRecord's JSON
+  serialization support.  You can use :only and :except options
+  to specify the columns included, :include to specify associations
+  to include, as well pass options to nested associations using a
+  hash.  In addition to serializing to JSON, it also adds support
+  for parsing JSON to model objects via JSON.parse or #from_json.
+  
+* An xml_serializer plugin was added that allows you to serialize
+  model instances or datasets to XML.  It requries the nokogiri
+  library.  It has a similar API to the json_serializer plugin, using
+  to_xml instead of to_json, and the from_xml class method instead
+  of JSON.parse.
+
+* A tree plugin was added that allows you to treat Sequel::Model
+  objects as being part of a tree.  It provides similar features to
+  rcte_tree, but works on databases that don't support recursive
+  common table expressions.  In addition to the standard parent
+  and children associations, it provides instance methods to get
+  the ancestors, descendants, and siblings of the given tree node,
+  and class methods to get the roots of the tree.
+
+* A list plugin was added that allows you to treat Sequel::Model
+  objects as being part of a list.  This adds instance methods to
+  get the next and prev items in the list, or to move the item
+  to a specific place in the list.  You can specify that all rows
+  in the table belong to the same list, or specify arbitrary scopes
+  so that the same table can contain many separate lists.
+
+= Other New Features
+
+* Sequel is now compatible with Ruby 1.9.2pre3.
+
+* Sequel now supports prepared transactions/two-phase commit on
+  PostgreSQL, MySQL, and H2.  You can specify that you want to
+  use prepared transactions using the :prepare option which
+  should be some transaction id string:
+  
+    DB.transaction(:prepare=>'some string') do ... end
+    
+  Assuming that no exceptions are raised in the transaction block,
+  Sequel will prepare the transaction.  You can then commit the
+  transaction later:
+  
+    DB.commit_prepared_transaction('some string')
+    
+  If you need to rollback the prepared transaction, you can do
+  so as well:
+  
+    DB.rollback_prepared_transaction('some string')
+
+* Sequel now supports customizable transaction isolation levels on
+  PostgreSQL, MySQL, and Microsoft SQL Server.  You can specify the
+  transaction isolation level to use for any transaction using the
+  :isolation option with an :uncommitted, :committed, :repeatable,
+  or :serializable value:
+  
+    DB.transaction(:isolation=>:serializable) do ... end
+    
+  You can also set the default isolation level for transactions via
+  the transaction_isolation_level Database attribute:
+  
+    DB.transaction_isolation_level = :committed
+    
+  If you are connecting to Microsoft SQL Server, it is recommended
+  that you set a default transaction isolation level if you plan
+  on using this feature.
+
+* You can specify a NULLS FIRST/LAST ordering by using the
+  :nulls=>:first/:last option to asc and desc:
+  
+    Album.filter(:release_date.desc(:nulls=>:first),
+                 :name.asc(:nulls=>:last))
+    # ORDER BY release_date DESC NULLS FIRST,
+    #          name ASC NULLS LAST
+
+  This syntax is supported by PostgreSQL 8.3+, Firebird 1.5+,
+  Oracle, and probably some other databases as well, and makes it
+  possible for the user to specify whether NULL values should sort
+  before or after other values.
+
+* Sequel::Model.find_or_create now accepts a block that is a yielded
+  a new model object to be created if an existing model object is
+  not found.  
+  
+    Node.find_or_create(:name=>'A'){|i| i.parent_id = 4}
+
+* The :frame option for windows and window functions can now be a
+  string that is used literally in the SQL.  This is necessary if you
+  want to specify a custom frame, such as one that uses a specific
+  number of rows preceding or following.
+
+* Savepoints are now supported on H2.
+
+* A :methods_module association option was added, allowing you to
+  specify the module into which association instance methods are
+  placed.  By default, it uses the module containing the column
+  accessor methods.
+
+= Other Improvements
+
+* The :encoding option for the native MySQL adapter should now work
+  correctly in all cases.  This fix was included in 3.12.1.
+
+* Sequel now handles arrays of two element arrays automatically when
+  using them as the value of a filter hash:
+  
+    DB[a].filter([:a, :b]=>[[1, 2], [3, 4]])
+    
+  Previously, you had to call .sql_array on the array in order to
+  tell Sequel that it was a value list and not a conditions
+  specifier.
+
+* Sequel no longer attempts to use class polymorphism in the
+  class_table_inheritance plugin if you don't specify a cti_key.
+
+* When using the native SQLite adapter, prepared statements are now
+  cached per connection for increased performance.  Previously,
+  Sequel prepared a new statement for every query.
+
+* tinyint(1) columns are now handled as booleans when connecting to
+  MySQL via JDBC.
+  
+* On PostgreSQL, if no :schema option is provided for
+  Database#tables, #table_exists?, or #schema, and no default_schema
+  is used,  assume all schemas except the default non-public ones.
+  Previously, it assumed the public schema for tables and
+  table_exists?, but did not assume any schema for #schema.
+  
+  This fixes issues if you use table names that overlap with table
+  names in the information_schema, such as domains.  It's still
+  recommended that you specify a default_schema if you are using a
+  schema other than public.
+
+* Unsigned integers are now handled correctly in the schema dumper.
+
+* Sequel::SQL::PlaceholderLiteralString is now a GenericExpression
+  subclass, allowing you to treat it like most other Sequel
+  expression objects:
+  
+    '(a || ?)'.lit(:b).like('Test%')
+    # ((a || b) LIKE 'Test%')
+
+* Sequel now supports the bitwise shift operators (<< and >>) on
+  Microsoft SQL Server by emulating them.
+
+* Sequel now supports most bitwise operators (&, |, ^, <<, >>) on H2
+  by emulating them.  The bitwise complement operator is not yet
+  supported.
+
+* Sequel now logs the SQL queries that are sent when connecting to
+  MySQL.
+
+* If a plugin cannot be loaded, Sequel now gives a more detailed
+  error message.
+
+= Backwards Compatibility
+
+* Array#sql_array and the Sequel::SQL::SQLArray class are now
+  considered deprecated.  Use the Array#sql_value_list and the
+  Sequel::SQL::ValueList class instead.  SQLArray is now just
+  an alias for ValueList, but it now is an Array subclass instead
+  of a Sequel::SQL::Expression subclass.
+
+* Using the ruby bitwise xor operator (^) on PostgreSQL now uses
+  PostgreSQL's bitwise xor operator (#) instead of PostgreSQL's
+  exponentiation operator (^).  If you want exponentiation, use
+  the power function.
+  
+* Using the ruby bitwise complement operator (~) on MySQL now returns
+  a signed integer instead of an unsigned integer, for better
+  compatibility with other databases.
+  
+* Using nil as a case expression value (the 2nd argument to Hash#case
+  and Array#case) will now use NULL as the case expression value,
+  instead of omitting the case expression value:
+  
+    # 3.12.0
+    {1=>2}.case(0, nil)
+    # CASE WHEN 1 THEN 2 ELSE 0 END
+    
+    # 3.13.0
+    {1=>2}.case(0, nil)
+    # CASE NULL WHEN 1 THEN 2 ELSE 0 END
+    
+  In general, you would never use nil explicitly, but the new
+  behavior makes more sense if you have a variable that might be nil:
+  
+    parent_id = Node[1].parent_id
+    {1=>2}.case(0, parent_id)
+
+  If parent_id IS NULL/nil, then previously Sequel would have
+  generated unexpected SQL.  If you don't want a case expression
+  value to be used, do not pass a second argument to #case.
+  
+* Some internal transaction methods now take an optional options
+  hash, so if you have a custom adapter, you will need to make
+  changes.
+  
+* Some internal association methods now take an optional options
+  hash.
+  
+* Some Rakefile task names were modified in the name of consistency:
+
+    spec_coverage -> spec_cov
+    integration -> spec_integration
+    integration_cov -> spec_integration_cov