sequel 4.8.0 → 4.9.0

data/lib/sequel/dataset/graph.rb

@@ -90,11 +90,18 @@ module Sequel
       # Only allow table aliases that haven't been used
       raise_alias_error.call if @opts[:graph] && @opts[:graph][:table_aliases] && @opts[:graph][:table_aliases].include?(table_alias)
       
+      table_alias_qualifier = qualifier_from_alias_symbol(table_alias, table)
+      implicit_qualifier = options[:implicit_qualifier]
+      ds = self
+
       # Use a from_self if this is already a joined table (or from_self specifically disabled for graphs)
-      ds = (@opts[:graph_from_self] != false && !@opts[:graph] && (@opts[:from].length > 1 || @opts[:join])) ? from_self(:alias=>options[:from_self_alias] || first_source) : self
+      if (@opts[:graph_from_self] != false && !@opts[:graph] && (@opts[:from].length > 1 || @opts[:join]))
+        implicit_qualifier = options[:from_self_alias] || first_source
+        ds = ds.from_self(:alias=>implicit_qualifier)
+      end
       
       # Join the table early in order to avoid cloning the dataset twice
-      ds = ds.join_table(options[:join_type] || :left_outer, table, join_conditions, :table_alias=>table_alias, :implicit_qualifier=>options[:implicit_qualifier], :qualify=>options[:qualify], &block)
+      ds = ds.join_table(options[:join_type] || :left_outer, table, join_conditions, :table_alias=>table_alias_qualifier, :implicit_qualifier=>implicit_qualifier, :qualify=>options[:qualify], &block)
       opts = ds.opts
 
       # Whether to include the table in the result set
@@ -108,7 +115,8 @@ module Sequel
         select = opts[:select].dup
         [:column_aliases, :table_aliases, :column_alias_num].each{|k| graph[k] = graph[k].dup}
       else
-        master = alias_symbol(ds.first_source_alias)
+        qualifier = ds.first_source_alias
+        master = alias_symbol(qualifier)
         raise_alias_error.call if master == table_alias
         # Master hash storing all .graph related information
         graph = opts[:graph] = {}
@@ -143,11 +151,11 @@ module Sequel
               end
               column_aliases[column] = [master, column]
             end
-            select = qualified_expression(select, master)
+            select = qualified_expression(select, qualifier)
           else
             select = columns.map do |column|
               column_aliases[column] = [master, column]
-              SQL::QualifiedIdentifier.new(master, column)
+              SQL::QualifiedIdentifier.new(qualifier, column)
             end
           end
         end
@@ -179,9 +187,9 @@ module Sequel
               column_alias = :"#{column_alias}_#{column_alias_num}" 
               ca_num[column_alias] += 1
             end
-            [column_alias, SQL::AliasedExpression.new(SQL::QualifiedIdentifier.new(table_alias, column), column_alias)]
+            [column_alias, SQL::AliasedExpression.new(SQL::QualifiedIdentifier.new(table_alias_qualifier, column), column_alias)]
           else
-            ident = SQL::QualifiedIdentifier.new(table_alias, column)
+            ident = SQL::QualifiedIdentifier.new(table_alias_qualifier, column)
             [column, ident]
           end
           column_aliases[col_alias] = [table_alias, column]
@@ -229,6 +237,20 @@ module Sequel
 
     private
 
+    # Wrap the alias symbol in an SQL::Identifier if the identifier on which is based
+    # is an SQL::Identifier.  This works around cases where the alias symbol contains
+    # double embedded underscores which would be considered an implicit qualified identifier
+    # if not wrapped in an SQL::Identifier.
+    def qualifier_from_alias_symbol(aliaz, identifier)
+      identifier = identifier.column if identifier.is_a?(SQL::QualifiedIdentifier)
+      case identifier
+      when SQL::Identifier
+        Sequel.identifier(aliaz)
+      else
+        aliaz
+      end
+    end
+
     # Transform the hash of graph aliases and return a two element array
     # where the first element is an array of identifiers suitable to pass to
     # a select method, and the second is a new hash of preprocessed graph aliases.

data/lib/sequel/dataset/misc.rb

@@ -36,6 +36,12 @@ module Sequel
       o.is_a?(self.class) && db == o.db && opts == o.opts && sql == o.sql
     end
 
+    # An object representing the current date or time, should be an instance
+    # of Sequel.datetime_class.
+    def current_datetime
+      Sequel.datetime_class.now
+    end
+
     # Alias for ==
     def eql?(o)
       self == o

data/lib/sequel/dataset/placeholder_literalizer.rb

@@ -0,0 +1,164 @@
+module Sequel
+  class Dataset
+    # PlaceholderLiteralizer allows you to record the application of arbitrary changes
+    # to a dataset with placeholder arguments, recording where those placeholder arguments
+    # are used in the query.  When running the query, the literalization process is much
+    # faster as Sequel can skip most of the work it normal has to do when literalizing a
+    # dataset.
+    #
+    # Basically, this enables optimizations that allow Sequel to cache the SQL produced
+    # for a given dataset, so that it doesn't need to recompute that information every
+    # time.
+    #
+    # Example:
+    #
+    #   loader = Sequel::Dataset::PlaceholderLiteralizer.loader(DB[:items]) do |pl, ds|
+    #     ds.where(:id=>pl.arg).exclude(:name=>pl.arg).limit(1)
+    #   end
+    #   loader.first(1, "foo")
+    #   # SELECT * FROM items WHERE ((id = 1) AND (name != 'foo')) LIMIT 1
+    #   loader.first(2, "bar")
+    #   # SELECT * FROM items WHERE ((id = 2) AND (name != 'bar')) LIMIT 1
+    #
+    # Caveats:
+    #
+    # Note that this method does not handle all possible cases.  For example:
+    #
+    #   loader = Sequel::Dataset::PlaceholderLiteralizer.loader(DB[:items]) do |pl, ds|
+    #     ds.join(pl.arg, :item_id=>:id)
+    #   end
+    #   loader(:cart_items)
+    #  
+    # Will not qualify the item_id column with cart_items.  In this type of situation it's
+    # best to add a table alias when joining:
+    #
+    #   loader = Sequel::Dataset::PlaceholderLiteralizer.loader(DB[:items]) do |pl, ds|
+    #     ds.join(Sequel.as(pl.arg, :t), :item_id=>:id)
+    #   end
+    #   loader(:cart_items)
+    #
+    # There are other similar cases that are not handled, mainly when Sequel changes the
+    # SQL produced depending on the types of the arguments.
+    class PlaceholderLiteralizer
+      # A placeholder argument used by the PlaceholderLiteralizer.  This records the offset
+      # that the argument should be used in the resulting SQL.
+      class Argument
+        # Set the recorder, the argument position, and any transforming block to use
+        # for this placeholder.
+        def initialize(recorder, pos, transformer=nil)
+          @recorder = recorder
+          @pos = pos
+          @transformer = transformer
+        end
+
+        # Record the SQL query offset, argument position, and transforming block where the
+        # argument should be literalized.
+        def sql_literal_append(ds, sql)
+          @recorder.use(sql, @pos, @transformer)
+        end
+
+        # Return a new Argument object for the same recorder and argument position, but with a
+        # different transformer block.
+        def transform(&block)
+          Argument.new(@recorder, @pos, block)
+        end
+      end
+
+      # Records the offsets at which the placeholder arguments are used in
+      # the SQL query.
+      class Recorder
+        # Yields the receiver and the dataset to the block, which should
+        # call #arg on the receiver for each placeholder argument, and
+        # return the dataset that you want to load.
+        def loader(dataset)
+          @argn = -1
+          @args = []
+          ds = yield self, dataset
+          sql = ds.sql
+
+          last_offset = 0
+          fragments = @args.map do |used_sql, offset, arg, t|
+            raise Error, "placeholder literalizer argument literalized into different string than dataset returned" unless used_sql.equal?(sql)
+            a = [sql[last_offset...offset], arg, t]
+            last_offset = offset
+            a
+          end
+          final_sql = sql[last_offset..-1]
+
+          arity = @argn+1
+          PlaceholderLiteralizer.new(ds.clone, fragments, final_sql, arity)
+        end
+
+        # Return an Argument with the specified position, or the next position. In
+        # general you shouldn't mix calls with an argument and calls without an
+        # argument for the same receiver.
+        def arg(v=(no_arg_given = true; @argn+=1))
+          unless no_arg_given
+            @argn = v if @argn < v
+          end
+          Argument.new(self, v)
+        end
+
+        # Record the offset at which the argument is used in the SQL query, and any
+        # transforming
+        def use(sql, arg, transformer)
+          @args << [sql, sql.length, arg, transformer]
+        end
+      end
+
+      # Create a PlaceholderLiteralizer by yielding a Recorder and dataset to the
+      # given block, recording the offsets at which the recorders arguments
+      # are used in the query.
+      def self.loader(dataset, &block)
+        Recorder.new.loader(dataset, &block)
+      end
+
+      # Save the dataset, array of SQL fragments, and ending SQL string.
+      def initialize(dataset, fragments, final_sql, arity)
+        @dataset = dataset
+        @fragments = fragments
+        @final_sql = final_sql
+        @arity = arity
+      end
+
+      # Return an array of all objects by running the SQL query for the given arguments.
+      # If a block is given, yields all objects to the block after loading them.
+      def all(*args, &block)
+        @dataset.with_sql_all(sql(*args), &block)
+      end
+
+      # Run the SQL query for the given arguments, yielding each returned row to the block.
+      def each(*args, &block)
+        @dataset.with_sql_each(sql(*args), &block)
+      end
+
+      # Run the SQL query for the given arguments, returning the first row.
+      def first(*args)
+        @dataset.with_sql_first(sql(*args))
+      end
+
+      # Run the SQL query for the given arguments, returning the first value.  For this to
+      # make sense, the dataset should return a single row with a single value (or no rows).
+      def get(*args)
+        @dataset.with_sql_single_value(sql(*args))
+      end
+
+      # Return the SQL query to use for the given arguments.
+      def sql(*args)
+        raise Error, "wrong number of arguments (#{args.length} for #{@arity})" unless args.length == @arity
+        s = ''
+        ds = @dataset
+        @fragments.each do |sql, i, transformer|
+          s << sql
+          v = args.fetch(i)
+          v = transformer.call(v) if transformer
+          ds.literal_append(s, v)
+        end
+        if sql = @final_sql
+          s << sql
+        end
+        s
+      end
+    end
+  end
+end

data/lib/sequel/dataset/query.rb

@@ -1049,6 +1049,8 @@ module Sequel
         end
       when String
         LiteralString.new("(#{expr})")
+      when PlaceholderLiteralizer::Argument
+        expr.transform{|v| filter_expr(v)}
       else
         raise(Error, "Invalid filter argument: #{expr.inspect}")
       end

data/lib/sequel/dataset/sql.rb

@@ -62,15 +62,8 @@ module Sequel
       clone(:columns=>columns, :values=>values)._insert_sql
     end
     
-    # Returns a literal representation of a value to be used as part
-    # of an SQL expression. 
+    # Append a literal representation of a value to the given SQL string.
     # 
-    #   DB[:items].literal("abc'def\\") #=> "'abc''def\\\\'"
-    #   DB[:items].literal(:items__id) #=> "items.id"
-    #   DB[:items].literal([1, 2, 3]) => "(1, 2, 3)"
-    #   DB[:items].literal(DB[:items]) => "(SELECT * FROM items)"
-    #   DB[:items].literal(:x + 1 > :y) => "((x + 1) > y)"
-    #
     # If an unsupported object is given, an +Error+ is raised.
     def literal_append(sql, v)
       case v
@@ -104,9 +97,9 @@ module Sequel
       when Array
         literal_array_append(sql, v)
       when Time
-        sql << (v.is_a?(SQLTime) ? literal_sqltime(v) : literal_time(v))
+        v.is_a?(SQLTime) ? literal_sqltime_append(sql, v) : literal_time_append(sql, v)
       when DateTime
-        sql << literal_datetime(v)
+        literal_datetime_append(sql, v)
       when Date
         sql << literal_date(v)
       when Dataset
@@ -190,6 +183,9 @@ module Sequel
     AS = ' AS '.freeze
     ASC = ' ASC'.freeze
     BACKSLASH = "\\".freeze
+    BITCOMP_CLOSE = ") - 1)".freeze
+    BITCOMP_OPEN = "((0 - ".freeze
+    BITWISE_METHOD_MAP = {:& =>:BITAND, :| => :BITOR, :^ => :BITXOR}
     BOOL_FALSE = "'f'".freeze
     BOOL_TRUE = "'t'".freeze
     BRACKET_CLOSE =  ']'.freeze
@@ -295,13 +291,13 @@ module Sequel
       END
     end
 
-    # SQL fragment for AliasedExpression
+    # Append literalization of aliased expression to SQL string.
     def aliased_expression_sql_append(sql, ae)
       literal_append(sql, ae.expression)
       as_sql_append(sql, ae.alias)
     end
 
-    # SQL fragment for Array
+    # Append literalization of array to SQL string.
     def array_sql_append(sql, a)
       if a.empty?
         sql << ARRAY_EMPTY
@@ -312,7 +308,7 @@ module Sequel
       end
     end
 
-    # SQL fragment for BooleanConstants
+    # Append literalization of boolean constant to SQL string.
     def boolean_constant_sql_append(sql, constant)
       if (constant == true || constant == false) && !supports_where_true?
         sql << (constant == true ? CONDITION_TRUE : CONDITION_FALSE)
@@ -321,7 +317,7 @@ module Sequel
       end
     end
 
-    # SQL fragment for CaseExpression
+    # Append literalization of case expression to SQL string.
     def case_expression_sql_append(sql, ce)
       sql << CASE_OPEN
       if ce.expression?
@@ -341,7 +337,7 @@ module Sequel
       sql << CASE_END
     end
 
-    # SQL fragment for the SQL CAST expression
+    # Append literalization of cast expression to SQL string.
     def cast_sql_append(sql, expr, type)
       sql << CAST_OPEN
       literal_append(sql, expr)
@@ -349,12 +345,12 @@ module Sequel
       sql << PAREN_CLOSE
     end
 
-    # SQL fragment for specifying all columns in a given table
+    # Append literalization of column all selection to SQL string.
     def column_all_sql_append(sql, ca)
       qualified_identifier_sql_append(sql, ca.table, WILDCARD)
     end
 
-    # SQL fragment for the complex expression.
+    # Append literalization of complex expression to SQL string.
     def complex_expression_sql_append(sql, op, args)
       case op
       when *IS_OPERATORS
@@ -459,18 +455,18 @@ module Sequel
       end
     end
     
-    # SQL fragment for constants
+    # Append literalization of constant to SQL string.
     def constant_sql_append(sql, constant)
       sql << constant.to_s
     end
 
-    # SQL fragment for delayed evaluations, evaluating the
-    # object and literalizing the returned value.
+    # Append literalization of delayed evaluation to SQL string,
+    # causing the delayed evaluation proc to be evaluated.
     def delayed_evaluation_sql_append(sql, callable)
       literal_append(sql, callable.call)
     end
 
-    # SQL fragment specifying an emulated SQL function call.
+    # Append literalization of emulated function call to SQL string.
     # By default, assumes just the function name may need to
     # be emulated, adapters should set an EMULATED_FUNCTION_MAP
     # hash mapping emulated functions to native functions in
@@ -479,12 +475,12 @@ module Sequel
       _function_sql_append(sql, native_function_name(f.f), f.args)
     end
 
-    # SQL fragment specifying an SQL function call without emulation.
+    # Append literalization of function call to SQL string.
     def function_sql_append(sql, f)
       _function_sql_append(sql, f.f, f.args)
     end
 
-    # SQL fragment specifying a JOIN clause without ON or USING.
+    # Append literalization of JOIN clause without ON or USING to SQL string.
     def join_clause_sql_append(sql, jc)
       table = jc.table
       table_alias = jc.table_alias
@@ -494,14 +490,14 @@ module Sequel
       as_sql_append(sql, table_alias) if table_alias
     end
 
-    # SQL fragment specifying a JOIN clause with ON.
+    # Append literalization of JOIN ON clause to SQL string.
     def join_on_clause_sql_append(sql, jc)
       join_clause_sql_append(sql, jc)
       sql << ON
       literal_append(sql, filter_expr(jc.on))
     end
 
-    # SQL fragment specifying a JOIN clause with USING.
+    # Append literalization of JOIN USING clause to SQL string.
     def join_using_clause_sql_append(sql, jc)
       join_clause_sql_append(sql, jc)
       sql << USING
@@ -509,14 +505,13 @@ module Sequel
       sql << PAREN_CLOSE
     end
     
-    # SQL fragment for NegativeBooleanConstants
+    # Append literalization of negative boolean constant to SQL string.
     def negative_boolean_constant_sql_append(sql, constant)
       sql << NOT_SPACE
       boolean_constant_sql_append(sql, constant)
     end
 
-    # SQL fragment for the ordered expression, used in the ORDER BY
-    # clause.
+    # Append literalization of ordered expression to SQL string.
     def ordered_expression_sql_append(sql, oe)
       literal_append(sql, oe.expression)
       sql << (oe.descending ? DESC : ASC)
@@ -528,7 +523,7 @@ module Sequel
       end
     end
 
-    # SQL fragment for a literal string with placeholders
+    # Append literalization of placeholder literal string to SQL string.
     def placeholder_literal_string_sql_append(sql, pls)
       args = pls.args
       str = pls.str
@@ -572,8 +567,7 @@ module Sequel
       sql << PAREN_CLOSE if pls.parens
     end
 
-    # SQL fragment for the qualifed identifier, specifying
-    # a table and a column (or schema and table).
+    # Append literalization of qualified identifier to SQL string.
     # If 3 arguments are given, the 2nd should be the table/qualifier and the third should be
     # column/qualified.  If 2 arguments are given, the 2nd should be an SQL::QualifiedIdentifier.
     def qualified_identifier_sql_append(sql, table, column=(c = table.column; table = table.table; c))
@@ -582,6 +576,7 @@ module Sequel
       identifier_append(sql, column)
     end
 
+    # Append literalization of unqualified identifier to SQL string.
     # Adds quoting to identifiers (columns and tables). If identifiers are not
     # being quoted, returns name as a string.  If identifiers are being quoted
     # quote the name with quoted_identifier.
@@ -599,8 +594,7 @@ module Sequel
       end
     end
 
-    # Separates the schema from the table and returns a string with them
-    # quoted (if quoting identifiers)
+    # Append literalization of identifier or unqualified identifier to SQL string.
     def quote_schema_table_append(sql, table)
       schema, table = schema_and_table(table)
       if schema
@@ -610,6 +604,7 @@ module Sequel
       quote_identifier_append(sql, table)
     end
 
+    # Append literalization of quoted identifier to SQL string.
     # This method quotes the given name with the SQL standard double quote. 
     # should be overridden by subclasses to provide quoting not matching the
     # SQL standard, such as backtick (used by MySQL and SQLite).
@@ -657,7 +652,7 @@ module Sequel
       end
     end
 
-    # SQL fragment for specifying subscripts (SQL array accesses)
+    # Append literalization of subscripts (SQL array accesses) to SQL string.
     def subscript_sql_append(sql, s)
       literal_append(sql, s.f)
       sql << BRACKET_OPEN
@@ -673,7 +668,7 @@ module Sequel
       sql << BRACKET_CLOSE
     end
 
-    # The SQL fragment for the given window's options.
+    # Append literalization of windows (for window functions) to SQL string.
     def window_sql_append(sql, opts)
       raise(Error, 'This dataset does not support window functions') unless supports_window_functions?
       sql << PAREN_OPEN
@@ -714,7 +709,7 @@ module Sequel
       sql << PAREN_CLOSE
     end
 
-    # The SQL fragment for the given window function's function and window.
+    # Append literalization of window function calls to SQL string.
     def window_function_sql_append(sql, function, window)
       literal_append(sql, function)
       sql << OVER
@@ -815,7 +810,7 @@ module Sequel
       options_overlap(COUNT_FROM_SELF_OPTS) ? from_self : unordered
     end
 
-    # SQL fragment for specifying an alias.  expression should already be literalized.
+    # Append aliasing expression to SQL string.
     def as_sql_append(sql, aliaz)
       sql << AS
       quote_identifier_append(sql, aliaz)
@@ -840,6 +835,7 @@ module Sequel
       sql
     end
 
+    # Append column list to SQL string.
     # Converts an array of column names into a comma seperated string of 
     # column names. If the array is empty, a wildcard (*) is returned.
     def column_list_append(sql, columns)
@@ -850,24 +846,50 @@ module Sequel
       end
     end
 
-    # Yield each two pair of arguments to the block, which should
-    # return a string representing the SQL code for those
-    # two arguments.  If more than 2 arguments are provided, all
-    # calls to the block # after the first will have a LiteralString
-    # as the first argument, representing the application of the block to
-    # the previous arguments.
+    # Yield each pair of arguments to the block, which should
+    # return an object representing the SQL expression for those
+    # two arguments.  For more than two arguments, the first
+    # argument to the block will be result of the previous block call.
     def complex_expression_arg_pairs(args)
       case args.length
       when 1
-        literal(args.at(0))
+        args.at(0)
       when 2
         yield args.at(0), args.at(1)
       else
-        args.inject{|m, a| LiteralString.new(yield(m, a))}
+        args.inject{|m, a| yield(m, a)}
+      end
+    end
+
+    # Append the literalization of the args using complex_expression_arg_pairs
+    # to the given SQL string, used when database operator/function is 2-ary
+    # where Sequel expression is N-ary.
+    def complex_expression_arg_pairs_append(sql, args, &block)
+      literal_append(sql, complex_expression_arg_pairs(args, &block))
+    end
+
+    # Append literalization of complex expression to SQL string, for
+    # operators unsupported by some databases. Used by adapters for databases
+    # that don't support the operators natively.
+    def complex_expression_emulate_append(sql, op, args)
+      case op
+      when :%
+        complex_expression_arg_pairs_append(sql, args){|a, b| Sequel.function(:MOD, a, b)}
+      when :>>
+        complex_expression_arg_pairs_append(sql, args){|a, b| Sequel./(a, Sequel.function(:power, 2, b))}
+      when :<<
+        complex_expression_arg_pairs_append(sql, args){|a, b| Sequel.*(a, Sequel.function(:power, 2, b))}
+      when :&, :|, :^
+        f = BITWISE_METHOD_MAP[op]
+        complex_expression_arg_pairs_append(sql, args){|a, b| Sequel.function(f, a, b)}
+      when :'B~'
+        sql << BITCOMP_OPEN
+        literal_append(sql, args.at(0))
+        sql << BITCOMP_CLOSE
       end
     end
 
-    # The SQL to use for the dataset used in a UNION/INTERSECT/EXCEPT clause. 
+    # Append literalization of dataset used in UNION/INTERSECT/EXCEPT clause to SQL string.
     def compound_dataset_sql_append(sql, ds)
       subselect_sql_append(sql, ds)
     end
@@ -891,8 +913,7 @@ module Sequel
       sql << DELETE
     end
 
-    # Converts an array of expressions into a comma separated string of
-    # expressions.
+    # Append literalization of array of expressions to SQL string.
     def expression_list_append(sql, columns)
       c = false
       co = COMMA
@@ -941,8 +962,8 @@ module Sequel
       sprintf(FORMAT_TIMESTAMP_USEC, usec)
     end
 
-    # Append the value, but special case regular (non-literal, non-blob) strings
-    # so that they are considered as identifiers and not SQL strings.
+    # Append literalization of identifier to SQL string, considering regular strings
+    # as SQL identifiers instead of SQL strings.
     def identifier_append(sql, v)
       if v.is_a?(String)
         case v
@@ -958,7 +979,7 @@ module Sequel
       end
     end
 
-    # Append all identifiers in args interspersed by commas.
+    # Append literalization of array of identifiers to SQL string.
     def identifier_list_append(sql, args)
       c = false
       comma = COMMA
@@ -975,7 +996,6 @@ module Sequel
       (i = identifier_input_method) ? v.to_s.send(i) : v.to_s
     end
 
-    # SQL fragment specifying the table to insert INTO
     def insert_into_sql(sql)
       sql << INTO
       source_list_append(sql, @opts[:from])
@@ -986,7 +1006,6 @@ module Sequel
       INSERT_CLAUSE_METHODS
     end
 
-    # SQL fragment specifying the columns to insert into
     def insert_columns_sql(sql)
       columns = opts[:columns]
       if columns && !columns.empty?
@@ -1000,7 +1019,6 @@ module Sequel
       sql << INSERT
     end
 
-    # SQL fragment specifying the values to insert.
     def insert_values_sql(sql)
       case values = opts[:values]
       when Array
@@ -1020,7 +1038,6 @@ module Sequel
       end
     end
 
-    # SQL fragment specifying the values to return.
     def insert_returning_sql(sql)
       if opts.has_key?(:returning)
         sql << RETURNING
@@ -1041,7 +1058,8 @@ module Sequel
      (opts[:from].is_a?(Array) && opts[:from].size > 1) || opts[:join]
     end
 
-    # SQL fragment for Array.  Treats as an expression if an array of all two pairs, or as a SQL array otherwise.
+    # Append a literalization of the array to SQL string.
+    # Treats as an expression if an array of all two pairs, or as a SQL array otherwise.
     def literal_array_append(sql, v)
       if Sequel.condition_specifier?(v)
         literal_expression_append(sql, SQL::BooleanExpression.from_value_pairs(v))
@@ -1056,12 +1074,12 @@ module Sequel
       v.nan? || v.infinite? ?  "'#{d}'" : d
     end
 
-    # SQL fragment for SQL::Blob
+    # Append literalization of SQL::Blob to SQL string.
     def literal_blob_append(sql, v)
       literal_string_append(sql, v)
     end
 
-    # SQL fragment for Dataset.  Does a subselect inside parantheses.
+    # Append literalization of dataset to SQL string.  Does a subselect inside parantheses.
     def literal_dataset_append(sql, v)
       sql << LATERAL if v.opts[:lateral]
       sql << PAREN_OPEN
@@ -1083,7 +1101,12 @@ module Sequel
       format_timestamp(v)
     end
 
-    # SQL fragment for SQL::Expression, result depends on the specific type of expression.
+    # Append literalization of DateTime to SQL string.
+    def literal_datetime_append(sql, v)
+      sql << literal_datetime(v)
+    end
+
+    # Append literalization of SQL::Expression to SQL string.
     def literal_expression_append(sql, v)
       v.to_s_append(self, sql)
     end
@@ -1098,7 +1121,7 @@ module Sequel
       v.to_s
     end
 
-    # SQL fragment for Hash, treated as an expression
+    # Append literalization of Hash to SQL string, treating hash as a boolean expression.
     def literal_hash_append(sql, v)
       literal_expression_append(sql, SQL::BooleanExpression.from_value_pairs(v))
     end
@@ -1113,11 +1136,9 @@ module Sequel
       NULL
     end
 
-    # SQL fragment for a type of object not handled by Dataset#literal.
-    # Calls +sql_literal+ if object responds to it, otherwise raises an error.
-    # Classes implementing +sql_literal+ should call a class-specific method on the dataset
-    # provided and should add that method to Sequel::Dataset, allowing for adapters
-    # to provide customized literalizations.
+    # Append a literalization of the object to the given SQL string.
+    # Calls +sql_literal_append+ if object responds to it, otherwise
+    # calls +sql_literal+ if object responds to it, otherwise raises an error.
     # If a database specific type is allowed, this should be overriden in a subclass.
     def literal_other_append(sql, v)
       if v.respond_to?(:sql_literal_append)
@@ -1134,19 +1155,17 @@ module Sequel
       v.strftime("'%H:%M:%S#{format_timestamp_usec(v.usec) if supports_timestamp_usecs?}'")
     end
 
-    # SQL fragment for String.  Doubles \ and ' by default.
+    # Append literalization of Sequel::SQLTime to SQL string.
+    def literal_sqltime_append(sql, v)
+      sql << literal_sqltime(v)
+    end
+
+    # Append literalization of string to SQL string.
     def literal_string_append(sql, v)
       sql << APOS << v.gsub(APOS_RE, DOUBLE_APOS) << APOS
     end
 
-    # Converts a symbol into a column name. This method supports underscore
-    # notation in order to express qualified (two underscores) and aliased
-    # (three underscores) columns:
-    #
-    #   dataset.literal(:abc) #=> "abc"
-    #   dataset.literal(:abc___a) #=> "abc AS a"
-    #   dataset.literal(:items__abc) #=> "items.abc"
-    #   dataset.literal(:items__abc___a) #=> "items.abc AS a"
+    # Append literalization of symbol to SQL string.
     def literal_symbol_append(sql, v)
       c_table, column, c_alias = split_symbol(v)
       if c_table
@@ -1162,6 +1181,11 @@ module Sequel
       format_timestamp(v)
     end
 
+    # Append literalization of Time to SQL string.
+    def literal_time_append(sql, v)
+      sql << literal_time(v)
+    end
+
     # SQL fragment for true
     def literal_true
       BOOL_TRUE
@@ -1203,13 +1227,11 @@ module Sequel
       SELECT_CLAUSE_METHODS
     end
 
-    # Modify the sql to add the columns selected
     def select_columns_sql(sql)
       sql << SPACE
       column_list_append(sql, @opts[:select])
     end
 
-    # Modify the sql to add the DISTINCT modifier
     def select_distinct_sql(sql)
       if distinct = @opts[:distinct]
         sql << DISTINCT
@@ -1234,7 +1256,6 @@ module Sequel
       end
     end
 
-    # Modify the sql to add the list of tables to select FROM
     def select_from_sql(sql)
       if f = @opts[:from]
         sql << FROM
@@ -1243,7 +1264,6 @@ module Sequel
     end
     alias delete_from_sql select_from_sql
 
-    # Modify the sql to add the expressions to GROUP BY
     def select_group_sql(sql)
       if group = @opts[:group]
         sql << GROUP_BY
@@ -1262,7 +1282,6 @@ module Sequel
       end
     end
 
-    # Modify the sql to add the filter criteria in the HAVING clause
     def select_having_sql(sql)
       if having = @opts[:having]
         sql << HAVING
@@ -1270,14 +1289,12 @@ module Sequel
       end
     end
 
-    # Modify the sql to add the list of tables to JOIN to
     def select_join_sql(sql)
       if js = @opts[:join]
         js.each{|j| literal_append(sql, j)}
       end
     end
 
-    # Modify the sql to limit the number of rows returned and offset
     def select_limit_sql(sql)
       if l = @opts[:limit]
         sql << LIMIT
@@ -1289,7 +1306,6 @@ module Sequel
       end
     end
   
-    # Modify the sql to support the different types of locking modes.
     def select_lock_sql(sql)
       case l = @opts[:lock]
       when :update
@@ -1299,7 +1315,6 @@ module Sequel
       end
     end
 
-    # Modify the sql to add the expressions to ORDER BY
     def select_order_sql(sql)
       if o = @opts[:order]
         sql << ORDER_BY
@@ -1313,7 +1328,6 @@ module Sequel
       sql << SELECT
     end
 
-    # Modify the sql to add the filter criteria in the WHERE clause
     def select_where_sql(sql)
       if w = @opts[:where]
         sql << WHERE
@@ -1323,7 +1337,6 @@ module Sequel
     alias delete_where_sql select_where_sql
     alias update_where_sql select_where_sql
     
-    # SQL Fragment specifying the WITH clause
     def select_with_sql(sql)
       ws = opts[:with]
       return if !ws || ws.empty?
@@ -1353,7 +1366,8 @@ module Sequel
       SQL_WITH
     end
 
-    # Converts an array of source names into into a comma separated list.
+    # Append literalization of array of sources/tables to SQL string, raising an Error if there
+    # are no sources.
     def source_list_append(sql, sources)
       raise(Error, 'No source specified for query') if sources.nil? || sources == []
       identifier_list_append(sql, sources)
@@ -1372,7 +1386,8 @@ module Sequel
     
     # SQL to use if this dataset uses static SQL.  Since static SQL
     # can be a PlaceholderLiteralString in addition to a String,
-    # we literalize nonstrings.
+    # we literalize nonstrings.  If there is an append_sql for this
+    # dataset, append to that SQL instead of returning the value.
     def static_sql(sql)
       if append_sql = @opts[:append_sql]
         if sql.is_a?(String)
@@ -1389,7 +1404,7 @@ module Sequel
       end
     end
 
-    # SQL fragment for a subselect using the given database's SQL.
+    # Append literalization of the subselect to SQL String.
     def subselect_sql_append(sql, ds)
       ds.clone(:append_sql=>sql).sql
     end
@@ -1399,15 +1414,12 @@ module Sequel
       UPDATE_CLAUSE_METHODS
     end
 
-    # SQL fragment specifying the tables from with to delete.
-    # Includes join table if modifying joins is allowed.
     def update_table_sql(sql)
       sql << SPACE
       source_list_append(sql, @opts[:from])
       select_join_sql(sql) if supports_modifying_joins?
     end
 
-    # The SQL fragment specifying the columns and values to SET.
     def update_set_sql(sql)
       values = opts[:values]
       sql << SET