sequel 3.12.1 → 3.13.0

data/lib/sequel/core_sql.rb

@@ -1,8 +1,8 @@
-# Sequel extends the Array class to add methods to implement the SQL DSL.
+# Sequel extends +Array+ to add methods to implement the SQL DSL.
 # Most of these methods require that the array not be empty and that it
 # must consist solely of other arrays that have exactly two elements.
 class Array
-  # Return a Sequel::SQL::BooleanExpression created from this array, not matching all of the
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this array, not matching all of the
   # conditions.
   #
   #   ~[[:a, true]] # SQL: a IS NOT TRUE
@@ -11,8 +11,8 @@ class Array
     sql_expr_if_all_two_pairs(:OR, true)
   end
 
-  # True if the array is not empty and all of its elements are
-  # arrays of size 2, false otherwise.  This is used to determine if the array
+  # +true+ if the array is not empty and all of its elements are
+  # arrays of size 2, +false+ otherwise.  This is used to determine if the array
   # could be a specifier of conditions, used similarly to a hash
   # but allowing for duplicate keys and a specific order.
   #
@@ -24,28 +24,37 @@ class Array
     !empty? && all?{|i| (Array === i) && (i.length == 2)}
   end
 
-  # Return a Sequel::SQL::CaseExpression with this array as the conditions and the given
+  # Return a <tt>Sequel::SQL::CaseExpression</tt> with this array as the conditions and the given
   # default value and expression.
   #
   #   [[{:a=>[2,3]}, 1]].case(0) # SQL: CASE WHEN a IN (2, 3) THEN 1 ELSE 0 END
   #   [[:a, 1], [:b, 2]].case(:d, :c) # SQL: CASE c WHEN a THEN 1 WHEN b THEN 2 ELSE d END
-  def case(default, expression = nil)
-    ::Sequel::SQL::CaseExpression.new(self, default, expression)
+  def case(*args)
+    ::Sequel::SQL::CaseExpression.new(self, *args)
   end
 
-  # Return a Sequel::SQL::Array created from this array.  Used if this array contains
-  # all two pairs and you want it treated as an SQL array instead of a ordered hash-like
-  # conditions.
+  # Return a <tt>Sequel::SQL::ValueList</tt> created from this array.  Used if this array contains
+  # all two element arrays and you want it treated as an SQL value list (IN predicate) 
+  # instead of as a conditions specifier (similar to a hash).  This is not necessary if you are using
+  # this array as a value in a filter, but may be necessary if you are using it as a
+  # value with placeholder SQL:
   #
-  #   [[1, 2], [3, 4]] # SQL: 1 = 2 AND 3 = 4
-  #   [[1, 2], [3, 4]].sql_array # SQL: ((1, 2), (3, 4))
-  def sql_array
-    ::Sequel::SQL::SQLArray.new(self)
+  #   DB[:a].filter([:a, :b]=>[[1, 2], [3, 4]]) # SQL: (a, b) IN ((1, 2), (3, 4))
+  #   DB[:a].filter('(a, b) IN ?', [[1, 2], [3, 4]]) # SQL: (a, b) IN ((1 = 2) AND (3 = 4))
+  #   DB[:a].filter('(a, b) IN ?', [[1, 2], [3, 4]].sql_value_list) # SQL: (a, b) IN ((1, 2), (3, 4))
+  def sql_value_list
+    ::Sequel::SQL::ValueList.new(self)
   end
+  
+  # Deprecated alias for sql_value_list
+  alias sql_array sql_value_list
 
-  # Return a Sequel::SQL::BooleanExpression created from this array, matching all of the
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this array, matching all of the
   # conditions.  Rarely do you need to call this explicitly, as Sequel generally
-  # assumes that arrays of all two pairs specify this type of condition.
+  # assumes that arrays of two element arrays specify this type of condition.  One case where
+  # it can be necessary to use this is if you are using the object as a value in a filter hash
+  # and want to use the = operator instead of the IN operator (which is used by default for
+  # arrays of two element arrays).
   #
   #   [[:a, true]].sql_expr # SQL: a IS TRUE
   #   [[:a, 1], [:b, [2, 3]]].sql_expr # SQL: a = 1 AND b IN (2, 3)
@@ -53,7 +62,7 @@ class Array
     sql_expr_if_all_two_pairs
   end
 
-  # Return a Sequel::SQL::BooleanExpression created from this array, matching none
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this array, matching none
   # of the conditions.
   #
   #   [[:a, true]].sql_negate # SQL: a IS NOT TRUE
@@ -62,7 +71,7 @@ class Array
     sql_expr_if_all_two_pairs(:AND, true)
   end
 
-  # Return a Sequel::SQL::BooleanExpression created from this array, matching any of the
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this array, matching any of the
   # conditions.
   #
   #   [[:a, true]].sql_or # SQL: a IS TRUE
@@ -71,10 +80,10 @@ class Array
     sql_expr_if_all_two_pairs(:OR)
   end
 
-  # Return a Sequel::SQL::BooleanExpression representing an SQL string made up of the
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> representing an SQL string made up of the
   # concatenation of this array's elements.  If an argument is passed
   # it is used in between each element of the array in the SQL
-  # concatenation.  This does not require that the array be made up of all two pairs.
+  # concatenation.
   #
   #   [:a].sql_string_join # SQL: a
   #   [:a, :b].sql_string_join # SQL: a || b
@@ -93,16 +102,16 @@ class Array
 
   private
 
-  # Raise an error if this array is not made up of all two pairs, otherwise create a Sequel::SQL::BooleanExpression from this array.
+  # Raise an error if this array is not made up all two element arrays, otherwise create a <tt>Sequel::SQL::BooleanExpression</tt> from this array.
   def sql_expr_if_all_two_pairs(*args)
     raise(Sequel::Error, 'Not all elements of the array are arrays of size 2, so it cannot be converted to an SQL expression') unless all_two_pairs?
     ::Sequel::SQL::BooleanExpression.from_value_pairs(self, *args)
   end
 end
 
-# Sequel extends the Hash class to add methods to implement the SQL DSL.
+# Sequel extends +Hash+ to add methods to implement the SQL DSL.
 class Hash
-  # Return a Sequel::SQL::BooleanExpression created from this hash, matching
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching
   # all of the conditions in this hash and the condition specified by
   # the given argument.
   #
@@ -112,7 +121,7 @@ class Hash
     ::Sequel::SQL::BooleanExpression.new(:AND, self, ce)
   end
 
-  # Return a Sequel::SQL::BooleanExpression created from this hash, matching
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching
   # all of the conditions in this hash or the condition specified by
   # the given argument.
   #
@@ -122,7 +131,7 @@ class Hash
     ::Sequel::SQL::BooleanExpression.new(:OR, self, ce)
   end
 
-  # Return a Sequel::SQL::BooleanExpression created from this hash, not matching all of the
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, not matching all of the
   # conditions.
   #
   #   ~{:a=>true} # SQL: a IS NOT TRUE
@@ -131,18 +140,18 @@ class Hash
     ::Sequel::SQL::BooleanExpression.from_value_pairs(self, :OR, true)
   end
 
-  # Return a Sequel::SQL::CaseExpression with this hash as the conditions and the given
-  # default value.  Note that the order of the conditions will be arbitrary, so all
+  # Return a <tt>Sequel::SQL::CaseExpression</tt> with this hash as the conditions and the given
+  # default value.  Note that the order of the conditions will be arbitrary on ruby 1.8, so all
   # conditions should be orthogonal.
   #
   #   {{:a=>[2,3]}=>1}.case(0) # SQL: CASE WHEN a IN (2, 3) THEN 1 ELSE 0 END
-  #   {:a=>1, {:b=>2}].case(:d, :c) # SQL: CASE c WHEN a THEN 1 WHEN b THEN 2 ELSE d END
+  #   {:a=>1, :b=>2}.case(:d, :c) # SQL: CASE c WHEN a THEN 1 WHEN b THEN 2 ELSE d END
   #                                 #  or: CASE c WHEN b THEN 2 WHEN a THEN 1 ELSE d END
-  def case(default, expression = nil)
-    ::Sequel::SQL::CaseExpression.new(to_a, default, expression)
+  def case(*args)
+    ::Sequel::SQL::CaseExpression.new(to_a, *args)
   end
 
-  # Return a Sequel::SQL::BooleanExpression created from this hash, matching all of the
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching all of the
   # conditions.  Rarely do you need to call this explicitly, as Sequel generally
   # assumes that hashes specify this type of condition.
   #
@@ -152,7 +161,7 @@ class Hash
     ::Sequel::SQL::BooleanExpression.from_value_pairs(self)
   end
 
-  # Return a Sequel::SQL::BooleanExpression created from this hash, matching none
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching none
   # of the conditions.
   #
   #   {:a=>true}.sql_negate # SQL: a IS NOT TRUE
@@ -161,7 +170,7 @@ class Hash
     ::Sequel::SQL::BooleanExpression.from_value_pairs(self, :AND, true)
   end
 
-  # Return a Sequel::SQL::BooleanExpression created from this hash, matching any of the
+  # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching any of the
   # conditions.
   #
   #   {:a=>true}.sql_or # SQL: a IS TRUE
@@ -171,12 +180,12 @@ class Hash
   end
 end
 
-# Sequel extends the String class to add methods to implement the SQL DSL.
+# Sequel extends +String+ to add methods to implement the SQL DSL.
 class String
   include Sequel::SQL::AliasMethods
   include Sequel::SQL::CastMethods
 
-  # Converts a string into a Sequel::LiteralString, in order to override string
+  # Converts a string into a <tt>Sequel::LiteralString</tt>, in order to override string
   # literalization, e.g.:
   #
   #   DB[:items].filter(:abc => 'def').sql #=>
@@ -185,7 +194,7 @@ class String
   #   DB[:items].filter(:abc => 'def'.lit).sql #=>
   #     "SELECT * FROM items WHERE (abc = def)"
   #
-  # You can also provide arguments, to create a Sequel::SQL::PlaceholderLiteralString:
+  # You can also provide arguments, to create a <tt>Sequel::SQL::PlaceholderLiteralString</tt>:
   #
   #    DB[:items].select{|o| o.count('DISTINCT ?'.lit(:a))}.sql #=>
   #      "SELECT count(DISTINCT a) FROM items"
@@ -193,14 +202,14 @@ class String
     args.empty? ? Sequel::LiteralString.new(self) : Sequel::SQL::PlaceholderLiteralString.new(self, args)
   end
   
-  # Returns a Sequel::SQL::Blob that holds the same data as this string. Blobs provide proper
+  # Returns a <tt>Sequel::SQL::Blob</tt> that holds the same data as this string. Blobs provide proper
   # escaping of binary data.
   def to_sequel_blob
     ::Sequel::SQL::Blob.new(self)
   end
 end
 
-# Sequel extends the Symbol class to add methods to implement the SQL DSL.
+# Sequel extends +Symbol+ to add methods to implement the SQL DSL.
 class Symbol
   include Sequel::SQL::QualifyingMethods
   include Sequel::SQL::IdentifierMethods
@@ -214,9 +223,9 @@ class Symbol
   include Sequel::SQL::ComplexExpressionMethods
   include Sequel::SQL::InequalityMethods if RUBY_VERSION < '1.9.0'
 
-  # If no argument is given, returns a Sequel::SQL::ColumnAll object specifying all
+  # If no argument is given, returns a <tt>Sequel::SQL::ColumnAll</tt> object specifying all
   # columns for this table.
-  # If an argument is given, returns a Sequel::SQL::NumericExpression using the *
+  # If an argument is given, returns a <tt>Sequel::SQL::NumericExpression</tt> using the *
   # (multiplication) operator with this and the given argument.
   # 
   #   :table.* # SQL: table.*
@@ -226,9 +235,9 @@ class Symbol
     Sequel::SQL::ColumnAll.new(self);
   end
 
-  # Returns a Sequel::SQL::Function  with this as the function name,
-  # and the given arguments. This is aliased as Symbol#[] if the RUBY_VERSION
-  # is less than 1.9.0. Ruby 1.9 defines Symbol#[], and Sequel
+  # Returns a <tt>Sequel::SQL::Function</tt> with this as the function name,
+  # and the given arguments. This is aliased as <tt>Symbol#[]</tt> if the RUBY_VERSION
+  # is less than 1.9.0. Ruby 1.9 defines <tt>Symbol#[]</tt>, and Sequel
   # doesn't override methods defined by ruby itself.
   #
   #   :now.sql_function # SQL: now()

data/lib/sequel/database/misc.rb

@@ -79,11 +79,22 @@ module Sequel
       {:primary_key => true, :type => Integer, :auto_increment => true}
     end
 
+    # Whether the database and adapter support prepared transactions
+    # (two-phase commit), false by default
+    def supports_prepared_transactions?
+      false
+    end
+
     # Whether the database and adapter support savepoints, false by default
     def supports_savepoints?
       false
     end
 
+    # Whether the database and adapter support transaction isolation levels, false by default
+    def supports_transaction_isolation_levels?
+      false
+    end
+
     # Typecast the value to the given column_type. Calls
     # typecast_value_#{column_type} if the method exists,
     # otherwise returns the value.

data/lib/sequel/database/query.rb

@@ -15,6 +15,11 @@ module Sequel
     TRANSACTION_BEGIN = 'Transaction.begin'.freeze
     TRANSACTION_COMMIT = 'Transaction.commit'.freeze
     TRANSACTION_ROLLBACK = 'Transaction.rollback'.freeze
+
+    TRANSACTION_ISOLATION_LEVELS = {:uncommitted=>'READ UNCOMMITTED'.freeze,
+      :committed=>'READ COMMITTED'.freeze,
+      :repeatable=>'REPEATABLE READ'.freeze,
+      :serializable=>'SERIALIZABLE'.freeze}
     
     POSTGRES_DEFAULT_RE = /\A(?:B?('.*')::[^']+|\((-?\d+(?:\.\d+)?)\))\z/
     MSSQL_DEFAULT_RE = /\A(?:\(N?('.*')\)|\(\((-?\d+(?:\.\d+)?)\)\))\z/
@@ -24,6 +29,13 @@ module Sequel
     # The prepared statement objects for this database, keyed by name
     attr_reader :prepared_statements
     
+    # The default transaction isolation level for this database,
+    # used for all future transactions.  For MSSQL, this should be set
+    # to something if you ever plan to use the :isolation option to
+    # Database#transaction, as on MSSQL if affects all future transactions
+    # on the same connection.
+    attr_accessor :transaction_isolation_level
+    
     # Runs the supplied SQL statement string on the database server.
     # Alias for run.
     def <<(sql)
@@ -142,15 +154,20 @@ module Sequel
     #
     # The following options are respected:
     #
-    # * :server  - The server to use for the transaction
-    # * :savepoint - Whether to create a new savepoint for this transaction,
-    #   only respected if the database adapter supports savepoints.  By
-    #   default Sequel will reuse an existing transaction, so if you want to
-    #   use a savepoint you must use this option.
+    # :isolation :: The transaction isolation level to use for this transaction,
+    #               should be :uncommitted, :committed, :repeatable, or :serializable.
+    # :prepare :: A string to use as the transaction identifier for a
+    #             prepared transaction (two-phase commit), if the database/adapter
+    #             supports prepared transactions
+    # :server :: The server to use for the transaction
+    # :savepoint :: Whether to create a new savepoint for this transaction,
+    #               only respected if the database adapter supports savepoints.  By
+    #               default Sequel will reuse an existing transaction, so if you want to
+    #               use a savepoint you must use this option.
     def transaction(opts={}, &block)
       synchronize(opts[:server]) do |conn|
         return yield(conn) if already_in_transaction?(conn, opts)
-        _transaction(conn, &block)
+        _transaction(conn, opts, &block)
       end
     end
     
@@ -160,17 +177,17 @@ module Sequel
     # block will cause the transaction to be rolled back.  If the exception is
     # not Sequel::Rollback, the error will be reraised. If no exception occurs
     # inside the block, the transaction is commited.
-    def _transaction(conn)
+    def _transaction(conn, opts={})
       begin
         add_transaction
-        t = begin_transaction(conn)
+        t = begin_transaction(conn, opts)
         yield(conn)
       rescue Exception => e
-        rollback_transaction(t) if t
+        rollback_transaction(t, opts) if t
         transaction_error(e)
       ensure
         begin
-          commit_transaction(t) unless e
+          commit_transaction(t, opts) unless e
         rescue Exception => e
           raise_error(e, :classes=>database_error_classes)
         ensure
@@ -202,15 +219,24 @@ module Sequel
       SQL_SAVEPOINT % depth
     end
 
-    # Start a new database transaction on the given connection.
-    def begin_transaction(conn)
+    # Start a new database connection on the given connection
+    def begin_new_transaction(conn, opts)
+      log_connection_execute(conn, begin_transaction_sql)
+      set_transaction_isolation(conn, opts)
+    end
+
+    # Start a new database transaction or a new savepoint on the given connection.
+    def begin_transaction(conn, opts={})
       if supports_savepoints?
         th = Thread.current
-        depth = th[:sequel_transaction_depth]
-        log_connection_execute(conn, depth > 0 ? begin_savepoint_sql(depth) : begin_transaction_sql)
+        if (depth = th[:sequel_transaction_depth]) > 0
+          log_connection_execute(conn, begin_savepoint_sql(depth))
+        else
+          begin_new_transaction(conn, opts)
+        end
         th[:sequel_transaction_depth] += 1
       else
-        log_connection_execute(conn, begin_transaction_sql)
+        begin_new_transaction(conn, opts)
       end
       conn
     end
@@ -276,7 +302,7 @@ module Sequel
     end
 
     # Commit the active transaction on the connection
-    def commit_transaction(conn)
+    def commit_transaction(conn, opts={})
       if supports_savepoints?
         depth = Thread.current[:sequel_transaction_depth]
         log_connection_execute(conn, depth > 1 ? commit_savepoint_sql(depth-1) : commit_transaction_sql)
@@ -343,7 +369,7 @@ module Sequel
     end
 
     # Rollback the active transaction on the connection
-    def rollback_transaction(conn)
+    def rollback_transaction(conn, opts={})
       if supports_savepoints?
         depth = Thread.current[:sequel_transaction_depth]
         log_connection_execute(conn, depth > 1 ? rollback_savepoint_sql(depth-1) : rollback_transaction_sql)
@@ -382,6 +408,18 @@ module Sequel
       end
     end
 
+    # Set the transaction isolation level on the given connection
+    def set_transaction_isolation(conn, opts)
+      if supports_transaction_isolation_levels? and level = opts.fetch(:isolation, transaction_isolation_level)
+        log_connection_execute(conn, set_transaction_isolation_sql(level))
+      end
+    end
+
+    # SQL to set the transaction isolation level
+    def set_transaction_isolation_sql(level)
+      "SET TRANSACTION ISOLATION LEVEL #{TRANSACTION_ISOLATION_LEVELS[level]}"
+    end
+
     # Raise a database error unless the exception is an Rollback.
     def transaction_error(e)
       raise_error(e, :classes=>database_error_classes) unless e.is_a?(Rollback)

data/lib/sequel/dataset/actions.rb

@@ -90,7 +90,8 @@ module Sequel
     #
     # Note that this method is not safe to use on many adapters if you are
     # running additional queries inside the provided block.  If you are
-    # running queries inside the block, you use should all instead of each.
+    # running queries inside the block, you should use +all+ instead of +each+
+    # for the outer queries, or use a separate thread or shard inside +each+.
     def each(&block)
       if @opts[:graph]
         graph_each(&block)

data/lib/sequel/dataset/query.rb

@@ -226,9 +226,8 @@ module Sequel
       group(*columns)
     end
     
-    # Returns a dataset grouped by the given column with count by group,
-    # order by the count of records. Column aliases may be supplied, and will
-    # be included in the select clause.
+    # Returns a dataset grouped by the given column with count by group.
+    # Column aliases may be supplied, and will be included in the select clause.
     #
     # Examples:
     #

data/lib/sequel/dataset/sql.rb

@@ -228,7 +228,7 @@ module Sequel
     # SQL fragment for specifying given CaseExpression.
     def case_expression_sql(ce)
       sql = '(CASE '
-      sql << "#{literal(ce.expression)} " if ce.expression
+      sql << "#{literal(ce.expression)} " if ce.expression?
       ce.conditions.collect{ |c,r|
         sql << "WHEN #{literal(c)} THEN #{literal(r)} "
       }
@@ -261,10 +261,10 @@ module Sequel
       when :IN, :"NOT IN"
         cols = args.at(0)
         vals = args.at(1)
-        col_array = true if cols.is_a?(Array) || cols.is_a?(SQL::SQLArray)
-        if vals.is_a?(Array) || vals.is_a?(SQL::SQLArray)
+        col_array = true if cols.is_a?(Array)
+        if vals.is_a?(Array)
           val_array = true
-          empty_val_array = vals.to_a == []
+          empty_val_array = vals == []
         end
         if col_array
           if empty_val_array
@@ -284,7 +284,10 @@ module Sequel
               complex_expression_sql(op, [cols, vals.map!{|x| x.values_at(*val_cols)}])
             end
           else
-            "(#{literal(cols)} #{op} #{literal(vals)})"
+            # If the columns and values are both arrays, use array_sql instead of
+            # literal so that if values is an array of two element arrays, it
+            # will be treated as a value list instead of a condition specifier.
+            "(#{literal(cols)} #{op} #{val_array ? array_sql(vals) : literal(vals)})"
           end
         else
           if empty_val_array
@@ -350,7 +353,15 @@ module Sequel
     # SQL fragment for the ordered expression, used in the ORDER BY
     # clause.
     def ordered_expression_sql(oe)
-      "#{literal(oe.expression)} #{oe.descending ? 'DESC' : 'ASC'}"
+      s = "#{literal(oe.expression)} #{oe.descending ? 'DESC' : 'ASC'}"
+      case oe.nulls
+      when :first
+        "#{s} NULLS FIRST"
+      when :last
+        "#{s} NULLS LAST"
+      else
+        s
+      end
     end
 
     # SQL fragment for a literal string with placeholders
@@ -434,8 +445,10 @@ module Sequel
           "ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING"
         when :rows
           "ROWS UNBOUNDED PRECEDING"
+        when String
+          opts[:frame]
         else
-          raise Error, "invalid window frame clause, should be :all, :rows, or nil"
+          raise Error, "invalid window frame clause, should be :all, :rows, a string, or nil"
       end
       "(#{[window, partition, order, frame].compact.join(' ')})"
     end
@@ -796,19 +809,19 @@ module Sequel
       when SQL::Identifier
         SQL::QualifiedIdentifier.new(table, e)
       when SQL::OrderedExpression
-        SQL::OrderedExpression.new(qualified_expression(e.expression, table), e.descending)
+        SQL::OrderedExpression.new(qualified_expression(e.expression, table), e.descending, :nulls=>e.nulls)
       when SQL::AliasedExpression
         SQL::AliasedExpression.new(qualified_expression(e.expression, table), e.aliaz)
       when SQL::CaseExpression
-        SQL::CaseExpression.new(qualified_expression(e.conditions, table), qualified_expression(e.default, table), qualified_expression(e.expression, table))
+        args = [qualified_expression(e.conditions, table), qualified_expression(e.default, table)]
+        args << qualified_expression(e.expression, table) if e.expression?
+        SQL::CaseExpression.new(*args)
       when SQL::Cast
         SQL::Cast.new(qualified_expression(e.expr, table), e.type)
       when SQL::Function
         SQL::Function.new(e.f, *qualified_expression(e.args, table))
       when SQL::ComplexExpression 
         SQL::ComplexExpression.new(e.op, *qualified_expression(e.args, table))
-      when SQL::SQLArray 
-        SQL::SQLArray.new(qualified_expression(e.array, table))
       when SQL::Subscript 
         SQL::Subscript.new(qualified_expression(e.f, table), qualified_expression(e.sub, table))
       when SQL::WindowFunction