sequel 3.12.1 → 3.13.0

data/lib/sequel/adapters/shared/postgres.rb

@@ -157,10 +157,17 @@ module Sequel
     
     # Methods shared by Database instances that connect to PostgreSQL.
     module DatabaseMethods
+      EXCLUDE_SCHEMAS = %w[pg_catalog pg_toast pg_temp_1 pg_toast_temp_1 information_schema]
       PREPARED_ARG_PLACEHOLDER = LiteralString.new('$').freeze
       RE_CURRVAL_ERROR = /currval of sequence "(.*)" is not yet defined in this session|relation "(.*)" does not exist/.freeze
       SYSTEM_TABLE_REGEXP = /^pg|sql/.freeze
 
+      # Commit an existing prepared transaction with the given transaction
+      # identifier string.
+      def commit_prepared_transaction(transaction_id)
+        run("COMMIT PREPARED #{literal(transaction_id)}")
+      end
+
       # Creates the function in the database.  Arguments:
       # * name : name of the function to create
       # * definition : string definition of the function, or object file for a dynamically loaded C function.
@@ -318,6 +325,12 @@ module Sequel
         get{setval(seq, db[table].select{coalesce(max(pk)+seq_ds.select{:increment_by}, seq_ds.select(:min_value))}, false)}
       end
 
+      # Rollback an existing prepared transaction with the given transaction
+      # identifier string.
+      def rollback_prepared_transaction(transaction_id)
+        run("ROLLBACK PREPARED #{literal(transaction_id)}")
+      end
+
       # PostgreSQL uses SERIAL psuedo-type instead of AUTOINCREMENT for
       # managing incrementing primary keys.
       def serial_primary_key_options
@@ -337,11 +350,23 @@ module Sequel
         @server_version
       end
       
+      # PostgreSQL supports prepared transactions (two-phase commit) if
+      # max_prepared_transactions is greater than 0.
+      def supports_prepared_transactions?
+        return @supports_prepared_transactions if defined?(@supports_prepared_transactions)
+        @supports_prepared_transactions = self['SHOW max_prepared_transactions'].get.to_i > 0
+      end
+
       # PostgreSQL supports savepoints
       def supports_savepoints?
         true
       end
 
+      # PostgreSQL supports transaction isolation levels
+      def supports_transaction_isolation_levels?
+        true
+      end
+
       # Whether the given table exists in the database
       #
       # Options:
@@ -362,13 +387,24 @@ module Sequel
       # * :schema - The schema to search (default_schema by default)
       # * :server - The server to use
       def tables(opts={})
-        ds = metadata_dataset.from(:pg_class).filter(:relkind=>'r').select(:relname).exclude(SQL::StringExpression.like(:relname, SYSTEM_TABLE_REGEXP)).server(opts[:server]).join(:pg_namespace, :oid=>:relnamespace, :nspname=>(opts[:schema]||default_schema||'public').to_s) 
+        ds = metadata_dataset.from(:pg_class).filter(:relkind=>'r').select(:relname).exclude(SQL::StringExpression.like(:relname, SYSTEM_TABLE_REGEXP)).server(opts[:server]).join(:pg_namespace, :oid=>:relnamespace) 
+        ds = filter_schema(ds, opts)
         m = output_identifier_meth
         block_given? ? yield(ds) : ds.map{|r| m.call(r[:relname])}
       end
 
       private
-      
+
+      # If the :prepare option is given and we aren't in a savepoint,
+      # prepare the transaction for a two-phase commit.
+      def commit_transaction(conn, opts={})
+        if opts[:prepare] && Thread.current[:sequel_transaction_depth] <= 1
+          log_connection_execute(conn, "PREPARE TRANSACTION #{literal(opts[:prepare])}")
+        else
+          super
+        end
+      end
+
       # SQL statement to create database function.
       def create_function_sql(name, definition, opts={})
         args = opts[:args]
@@ -427,6 +463,16 @@ module Sequel
         "DROP TRIGGER#{' IF EXISTS' if opts[:if_exists]} #{name} ON #{quote_schema_table(table)}#{' CASCADE' if opts[:cascade]}"
       end
 
+      # If opts includes a :schema option, or a default schema is used, restrict the dataset to
+      # that schema.  Otherwise, just exclude the default PostgreSQL schemas except for public.
+      def filter_schema(ds, opts)
+        if schema = opts[:schema] || default_schema
+          ds.filter(:pg_namespace__nspname=>schema.to_s)
+        else
+          ds.exclude(:pg_namespace__nspname=>EXCLUDE_SCHEMAS)
+        end
+      end
+      
       # PostgreSQL folds unquoted identifiers to lowercase, so it shouldn't need to upcase identifiers on input.
       def identifier_input_method_default
         nil
@@ -523,13 +569,14 @@ module Sequel
           from(:pg_class).
           join(:pg_attribute, :attrelid=>:oid).
           join(:pg_type, :oid=>:atttypid).
+          join(:pg_namespace, :oid=>:pg_class__relnamespace).
           left_outer_join(:pg_attrdef, :adrelid=>:pg_class__oid, :adnum=>:pg_attribute__attnum).
           left_outer_join(:pg_index, :indrelid=>:pg_class__oid, :indisprimary=>true).
           filter(:pg_attribute__attisdropped=>false).
           filter{|o| o.pg_attribute__attnum > 0}.
           filter(:pg_class__relname=>m2.call(table_name)).
           order(:pg_attribute__attnum)
-        ds.join!(:pg_namespace, :oid=>:pg_class__relnamespace, :nspname=>(opts[:schema] || default_schema).to_s) if opts[:schema] || default_schema
+        ds = filter_schema(ds, opts)
         ds.map do |row|
           row[:default] = nil if blank_object?(row[:default])
           row[:type] = schema_column_type(row[:db_type])
@@ -627,6 +674,17 @@ module Sequel
         explain(:analyze=>true)
       end
       
+      # Handle converting the ruby xor operator (^) into the
+      # PostgreSQL xor operator (#).
+      def complex_expression_sql(op, args)
+        case op
+        when :^
+          "(#{literal(args.at(0))} # #{literal(args.at(1))})"
+        else
+          super
+        end
+      end
+
       # Disable the use of INSERT RETURNING, even if the server supports it
       def disable_insert_returning
         clone(:disable_insert_returning=>true)

data/lib/sequel/adapters/sqlite.rb

@@ -61,6 +61,11 @@ module Sequel
         
         # Handle blob values with Sequel::SQL::Blob
         db.translator.add_translator("blob"){|t,v| ::Sequel::SQL::Blob.new(v)}
+
+        class << db
+          attr_reader :prepared_statements
+        end
+        db.instance_variable_set(:@prepared_statements, {})
         
         db
       end
@@ -70,39 +75,60 @@ module Sequel
         SQLite::Dataset.new(self, opts)
       end
       
+      # Run the given SQL with the given arguments and yield each row.
+      def execute(sql, opts={}, &block)
+        _execute(:select, sql, opts, &block)
+      end
+
       # Run the given SQL with the given arguments and return the number of changed rows.
       def execute_dui(sql, opts={})
-        _execute(opts){|conn| log_yield(sql, opts[:arguments]){conn.execute_batch(sql, opts.fetch(:arguments, []))}; conn.changes}
+        _execute(:update, sql, opts)
       end
       
-      # Run the given SQL with the given arguments and return the last inserted row id.
-      def execute_insert(sql, opts={})
-        _execute(opts){|conn| log_yield(sql, opts[:arguments]){conn.execute(sql, opts.fetch(:arguments, []))}; conn.last_insert_row_id}
+      # Drop any prepared statements on the connection when executing DDL.  This is because
+      # prepared statements lock the table in such a way that you can't drop or alter the
+      # table while a prepared statement that references it still exists.
+      def execute_ddl(sql, opts={})
+        synchronize(opts[:server]) do |conn|
+          conn.prepared_statements.values.each{|cps, s| cps.close}
+          conn.prepared_statements.clear
+          super
+        end
       end
       
-      # Run the given SQL with the given arguments and yield each row.
-      def execute(sql, opts={})
-        _execute(opts) do |conn|
-          begin
-            yield(result = log_yield(sql, opts[:arguments]){conn.query(sql, opts.fetch(:arguments, []))})
-          ensure
-            result.close if result
-          end
-        end
+      # Run the given SQL with the given arguments and return the last inserted row id.
+      def execute_insert(sql, opts={})
+        _execute(:insert, sql, opts)
       end
       
       # Run the given SQL with the given arguments and return the first value of the first row.
       def single_value(sql, opts={})
-        _execute(opts){|conn| log_yield(sql, opts[:arguments]){conn.get_first_value(sql, opts.fetch(:arguments, []))}}
+        _execute(:single_value, sql, opts)
       end
       
       private
       
       # Yield an available connection.  Rescue
       # any SQLite3::Exceptions and turn them into DatabaseErrors.
-      def _execute(opts, &block)
+      def _execute(type, sql, opts, &block)
         begin
-          synchronize(opts[:server], &block)
+          synchronize(opts[:server]) do |conn|
+            return execute_prepared_statement(conn, type, sql, opts, &block) if sql.is_a?(Symbol)
+            log_args = opts[:arguments]
+            args = opts.fetch(:arguments, [])
+            case type
+            when :select
+              log_yield(sql, log_args){conn.query(sql, args, &block)}
+            when :single_value
+              log_yield(sql, log_args){conn.get_first_value(sql, args)}
+            when :insert
+              log_yield(sql, log_args){conn.execute(sql, args)}
+              conn.last_insert_row_id
+            when :update
+              log_yield(sql, log_args){conn.execute_batch(sql, args)}
+              conn.changes
+            end
+          end
         rescue SQLite3::Exception => e
           raise_error(e)
         end
@@ -119,6 +145,35 @@ module Sequel
         o
       end
       
+      # Execute a prepared statement on the database using the given name.
+      def execute_prepared_statement(conn, type, name, opts, &block)
+        ps = prepared_statements[name]
+        sql = ps.prepared_sql
+        args = opts[:arguments]
+        if cpsa = conn.prepared_statements[name]
+          cps, cps_sql = cpsa
+          if cps_sql != sql
+            cps.close
+            cps = nil
+          end
+        end
+        unless cps
+          cps = conn.prepare(sql)
+          conn.prepared_statements[name] = [cps, sql]
+        end
+        if block
+          log_yield("Executing prepared statement #{name}", args){cps.execute(args, &block)}
+        else
+          log_yield("Executing prepared statement #{name}", args){cps.execute!(args){|r|}}
+          case type
+          when :insert
+            conn.last_insert_row_id
+          when :update
+            conn.changes
+          end
+        end
+      end
+      
       # The main error class that SQLite3 raises
       def database_error_classes
         [SQLite3::Exception]
@@ -161,7 +216,7 @@ module Sequel
       
       # SQLite prepared statement uses a new prepared statement each time
       # it is called, but it does use the bind arguments.
-      module PreparedStatementMethods
+      module BindArgumentMethods
         include ArgumentMapper
         
         private
@@ -182,6 +237,35 @@ module Sequel
           super(sql, {:arguments=>bind_arguments}.merge(opts), &block)
         end
       end
+
+      module PreparedStatementMethods
+        include BindArgumentMethods
+          
+        private
+          
+        # Execute the stored prepared statement name and the stored bind
+        # arguments instead of the SQL given.
+        def execute(sql, opts={}, &block)
+          super(prepared_statement_name, opts, &block)
+        end
+         
+        # Same as execute, explicit due to intricacies of alias and super.
+        def execute_dui(sql, opts={}, &block)
+          super(prepared_statement_name, opts, &block)
+        end
+          
+        # Same as execute, explicit due to intricacies of alias and super.
+        def execute_insert(sql, opts={}, &block)
+          super(prepared_statement_name, opts, &block)
+        end
+      end
+        
+      # Execute the given type of statement with the hash of values.
+      def call(type, bind_vars={}, *values, &block)
+        ps = to_prepared_statement(type, values)
+        ps.extend(BindArgumentMethods)
+        ps.call(bind_vars, &block)
+      end
       
       # Yield a hash for each row in the dataset.
       def fetch_rows(sql)
@@ -203,7 +287,10 @@ module Sequel
       def prepare(type, name=nil, *values)
         ps = to_prepared_statement(type, values)
         ps.extend(PreparedStatementMethods)
-        db.prepared_statements[name] = ps if name
+        if name
+          ps.prepared_statement_name = name
+          db.prepared_statements[name] = ps
+        end
         ps.prepared_sql
         ps
       end

data/lib/sequel/connection_pool.rb

@@ -1,31 +1,32 @@
-# The base connection pool class, which all other connection pools are built
+# The base connection pool class, which all other connection pools are based
 # on.  This class is not instantiated directly, but subclasses should at
 # the very least implement the following API:
-# * initialize(Hash, &block) - The block is used as the connection proc,
-#   which should accept a single symbol argument.
-# * hold(Symbol, &block) - yield a connection object (obtained from calling
-#   the block passed to initialize) to the current block. For sharded
-#   connection pools, the Symbol passed is the shard/server to use.
-# * disconnect(Symbol, &block) - disconnect the connection object.  If a
-#   block is given, pass the connection option to it, otherwise use the
-#   :disconnection_proc option in the hash passed to initialize.  For sharded
-#   connection pools, the Symbol passed is the shard/server to use.
-# * servers - an array of shard/server symbols for all shards/servers that this
-#   connection pool recognizes.
-# * size - an integer representing the total number of connections in the pool,
-#   or for the given shard/server if sharding is supported.
 #
-# For sharded connection pools, the sharded API:
-# * add_servers(Array of Symbols) - start recognizing all shards/servers specified
-#   by the array of symbols.
-# * remove_servers(Array of Symbols) - no longer recognize all shards/servers
-#   specified by the array of symbols.
+# initialize(Hash, &block) :: The +block+ is used as the connection proc,
+#                             which should accept a single symbol argument.
+# hold(Symbol, &block) :: Yield a connection object (obtained from calling
+#                         the block passed to +initialize+) to the current block. For sharded
+#                         connection pools, the Symbol passed is the shard/server to use.
+# disconnect(Symbol, &block) :: Disconnect the connection object.  If a
+#                               block is given, pass the connection option to it, otherwise use the
+#                               <tt>:disconnection_proc</tt> option in the hash passed to initialize.  For sharded
+#                               connection pools, the Symbol passed is the shard/server to use.
+# servers :: An array of shard/server symbols for all shards/servers that this
+#            connection pool recognizes.
+# size :: an integer representing the total number of connections in the pool,
+#         or for the given shard/server if sharding is supported.
+#
+# For sharded connection pools, the sharded API adds the following methods:
+#
+# add_servers(Array of Symbols) :: start recognizing all shards/servers specified
+#                                  by the array of symbols.
+# * remove_servers(Array of Symbols) :: no longer recognize all shards/servers
+#                                       specified by the array of symbols.
 class Sequel::ConnectionPool
   # The default server to use
   DEFAULT_SERVER = :default
   
-  # A map of [single threaded, sharded] values to files (indicating strings to
-  # be required) ConnectionPool subclasses.
+  # A map of [single threaded, sharded] values to symbols or ConnectionPool subclasses.
   CONNECTION_POOL_MAP = {[true, false] => :single, 
     [true, true] => :sharded_single,
     [false, false] => :threaded,
@@ -34,10 +35,10 @@ class Sequel::ConnectionPool
   # Class methods used to return an appropriate pool subclass, separated
   # into a module for easier overridding by extensions.
   module ClassMethods
-    # Return a pool subclass instance based on the given options.  If a :pool_class
+    # Return a pool subclass instance based on the given options.  If a <tt>:pool_class</tt>
     # option is provided is provided, use that pool class, otherwise
     # use a new instance of an appropriate pool subclass based on the
-    # :single_threaded and :servers options.
+    # <tt>:single_threaded</tt> and <tt>:servers</tt> options.
     def get_pool(opts = {}, &block)
       case v = connection_pool_class(opts)
       when Class
@@ -61,23 +62,23 @@ class Sequel::ConnectionPool
   # with a single symbol (specifying the server/shard to use) every time a new
   # connection is needed.  The following options are respected for all connection
   # pools:
-  # * :after_connect - The proc called after each new connection is made, with the
-  #   connection object, useful for customizations that you want to apply to all
-  #   connections.
-  # * :disconnection_proc - The proc called when removing connections from the pool,
-  #   which is passed the connection to disconnect.
+  # :after_connect :: The proc called after each new connection is made, with the
+  #                   connection object, useful for customizations that you want to apply to all
+  #                   connections.
+  # :disconnection_proc :: The proc called when removing connections from the pool,
+  #                        which is passed the connection to disconnect.
   def initialize(opts={}, &block)
     raise(Sequel::Error, "No connection proc specified") unless @connection_proc = block
     @disconnection_proc = opts[:disconnection_proc]
     @after_connect = opts[:after_connect]
   end
   
-  # Alias for size, not aliased directly for ease of subclass implementation
+  # Alias for +size+, not aliased directly for ease of subclass implementation
   def created_count(*args)
     size(*args)
   end
   
-  # An array of symbols for all shards/servers, which is a single :default by default.
+  # An array of symbols for all shards/servers, which is a single <tt>:default</tt> by default.
   def servers
     [:default]
   end

data/lib/sequel/core.rb

@@ -2,7 +2,7 @@
 
 # Top level module for Sequel
 #
-# There are some class methods that are added via metaprogramming, one for
+# There are some module methods that are added via metaprogramming, one for
 # each supported adapter.  For example:
 #
 #   DB = Sequel.sqlite # Memory database
@@ -17,34 +17,7 @@
 #
 #   Sequel.sqlite('blog.db'){|db| puts db[:users].count} 
 #
-# Sequel doesn't pay much attention to timezones by default, but you can set it
-# handle timezones if you want.  There are three separate timezone settings:
-#
-# * application_timezone - The timezone you want the application to use.  This is
-#   the timezone that incoming times from the database and typecasting are converted
-#   to.
-# * database_timezone - The timezone for storage in the database.  This is the
-#   timezone to which Sequel will convert timestamps before literalizing them
-#   for storage in the database.  It is also the timezone that Sequel will assume
-#   database timestamp values are already in (if they don't include an offset).
-# * typecast_timezone - The timezone that incoming data that Sequel needs to typecast
-#   is assumed to be already in (if they don't include an offset).
-#
-# You can set also set all three timezones to the same value at once via
-# Sequel.default_timezone=.
-#
-#   Sequel.application_timezone = :utc # or :local or nil
-#   Sequel.database_timezone = :utc # or :local or nil
-#   Sequel.typecast_timezone = :utc # or :local or nil
-#   Sequel.default_timezone = :utc # or :local or nil
-#
-# The only timezone values that are supported by default are :utc (convert to UTC),
-# :local (convert to local time), and nil (don't convert).  If you need to
-# convert to a specific timezone, or need the timezones being used to change based
-# on the environment (e.g. current user), you need to use an extension (and use
-# DateTime as the datetime_class).
-#
-# You can set the SEQUEL_NO_CORE_EXTENSIONS constant or environment variable to have
+# You can set the +SEQUEL_NO_CORE_EXTENSIONS+ constant or environment variable to have
 # Sequel not extend the core classes.
 #
 # For a more expanded introduction, see the {README}[link:files/README_rdoc.html].
@@ -55,20 +28,25 @@ module Sequel
   @virtual_row_instance_eval = true
   @require_thread = nil
   
-  # Mutex used to protect file loading
+  # Mutex used to protect file loading/requireing
   @require_mutex = Mutex.new
   
   class << self
-    # Sequel converts two digit years in Dates and DateTimes by default,
+    # Sequel converts two digit years in <tt>Date</tt>s and <tt>DateTime</tt>s by default,
     # so 01/02/03 is interpreted at January 2nd, 2003, and 12/13/99 is interpreted
     # as December 13, 1999. You can override this to treat those dates as
-    # January 2nd, 0003 and December 13, 0099, respectively, by setting this to false.
+    # January 2nd, 0003 and December 13, 0099, respectively, by:
+    #
+    #   Sequel.convert_two_digit_years = false
     attr_accessor :convert_two_digit_years
 
-    # Sequel can use either Time or DateTime for times returned from the
-    # database.  It defaults to Time.  To change it to DateTime, set this to DateTime.
+    # Sequel can use either +Time+ or +DateTime+ for times returned from the
+    # database.  It defaults to +Time+.  To change it to +DateTime+:
+    #
+    #   Sequel.datetime_class = DateTime
     attr_accessor :datetime_class
 
+    # For backwards compatibility, has no effect.
     attr_accessor :virtual_row_instance_eval
     
     # Alias to the standard version of require
@@ -92,14 +70,20 @@ module Sequel
   end
 
   # Returns true if the passed object could be a specifier of conditions, false otherwise.
-  # Currently, Sequel considers hashes and arrays of all two pairs as
+  # Currently, Sequel considers hashes and arrays of two element arrays as
   # condition specifiers.
+  #
+  #   Sequel.condition_specifier?({}) # => true
+  #   Sequel.condition_specifier?([[1, 2]]) # => true
+  #   Sequel.condition_specifier?([]) # => false
+  #   Sequel.condition_specifier?([1]) # => false
+  #   Sequel.condition_specifier?(1) # => false
   def self.condition_specifier?(obj)
     case obj
     when Hash
       true
     when Array
-      !obj.empty? && obj.all?{|i| (Array === i) && (i.length == 2)}
+      !obj.empty? && !obj.is_a?(SQL::ValueList) && obj.all?{|i| (Array === i) && (i.length == 2)}
     else
       false
     end
@@ -116,7 +100,7 @@ module Sequel
   #   DB = Sequel.connect('postgres://user:password@host:port/database_name')
   #   DB = Sequel.connect('sqlite:///blog.db', :max_connections=>10)
   #
-  # If a block is given, it is passed the opened Database object, which is
+  # If a block is given, it is passed the opened +Database+ object, which is
   # closed when the block exits.  For example:
   #
   #   Sequel.connect('sqlite://blog.db'){|db| puts db[:users].count}  
@@ -127,9 +111,9 @@ module Sequel
     Database.connect(*args, &block)
   end
   
-  # Convert the exception to the given class.  The given class should be
-  # Sequel::Error or a subclass.  Returns an instance of klass with
-  # the message and backtrace of exception.
+  # Convert the +exception+ to the given class.  The given class should be
+  # <tt>Sequel::Error</tt> or a subclass.  Returns an instance of +klass+ with
+  # the message and backtrace of +exception+.
   def self.convert_exception_class(exception, klass)
     return exception if exception.is_a?(klass)
     e = klass.new("#{exception.class}: #{exception.message}")
@@ -138,8 +122,13 @@ module Sequel
     e
   end
 
-  # Load all Sequel extensions given.  Only loads extensions included in this
-  # release of Sequel, doesn't load external extensions.
+  # Load all Sequel extensions given.  Extensions are just files that exist under
+  # <tt>sequel/extensions</tt> in the load path, and are just required.  Generally,
+  # extensions modify the behavior of +Database+ and/or +Dataset+, but Sequel ships
+  # with some extensions that modify other classes that exist for backwards compatibility.
+  # In some cases, requiring an extension modifies classes directly, and in others,
+  # it just loads a module that you can extend other classes with.  Consult the documentation
+  # for each extension you plan on using for usage.
   #
   #   Sequel.extension(:schema_dumper)
   #   Sequel.extension(:pagination, :query)
@@ -186,14 +175,16 @@ module Sequel
     Database.quote_identifiers = value
   end
   
-  # Require all given files which should be in the same or a subdirectory of
-  # this file.  If a subdir is given, assume all files are in that subdir.
+  # Require all given +files+ which should be in the same or a subdirectory of
+  # this file.  If a +subdir+ is given, assume all +files+ are in that subdir.
+  # This is used to ensure that the files loaded are from the same version of
+  # Sequel as this file.
   def self.require(files, subdir=nil)
     Array(files).each{|f| super("#{File.dirname(__FILE__)}/#{"#{subdir}/" if subdir}#{f}")}
   end
   
   # Set whether to set the single threaded mode for all databases by default. By default,
-  # Sequel uses a threadsafe connection pool, which isn't as fast as the
+  # Sequel uses a thread-safe connection pool, which isn't as fast as the
   # single threaded connection pool.  If your program will only have one thread,
   # and speed is a priority, you may want to set this to true:
   #
@@ -202,33 +193,39 @@ module Sequel
     Database.single_threaded = value
   end
 
-  # Converts the given string into a Date object.
-  def self.string_to_date(s)
+  # Converts the given +string+ into a +Date+ object.
+  #
+  #   Sequel.string_to_date('2010-09-10') # Date.civil(2010, 09, 10)
+  def self.string_to_date(string)
     begin
-      Date.parse(s, Sequel.convert_two_digit_years)
+      Date.parse(string, Sequel.convert_two_digit_years)
     rescue => e
       raise convert_exception_class(e, InvalidValue)
     end
   end
 
-  # Converts the given string into a Time or DateTime object, depending on the
-  # value of Sequel.datetime_class.
-  def self.string_to_datetime(s)
+  # Converts the given +string+ into a +Time+ or +DateTime+ object, depending on the
+  # value of <tt>Sequel.datetime_class</tt>.
+  #
+  #   Sequel.string_to_datetime('2010-09-10 10:20:30') # Time.local(2010, 09, 10, 10, 20, 30)
+  def self.string_to_datetime(string)
     begin
       if datetime_class == DateTime
-        DateTime.parse(s, convert_two_digit_years)
+        DateTime.parse(string, convert_two_digit_years)
       else
-        datetime_class.parse(s)
+        datetime_class.parse(string)
       end
     rescue => e
       raise convert_exception_class(e, InvalidValue)
     end
   end
 
-  # Converts the given string into a Time object.
-  def self.string_to_time(s)
+  # Converts the given +string+ into a +Time+ object.
+  #
+  #   Sequel.string_to_datetime('10:20:30') # Time.parse('10:20:30')
+  def self.string_to_time(string)
     begin
-      Time.parse(s)
+      Time.parse(string)
     rescue => e
       raise convert_exception_class(e, InvalidValue)
     end
@@ -245,9 +242,12 @@ module Sequel
   end
 
   # If the supplied block takes a single argument,
-  # yield a new SQL::VirtualRow instance to the block
+  # yield a new <tt>SQL::VirtualRow</tt> instance to the block
   # argument.  Otherwise, evaluate the block in the context of a new
-  # SQL::VirtualRow instance.
+  # <tt>SQL::VirtualRow</tt> instance.
+  #
+  #   Sequel.virtual_row{a} # Sequel::SQL::Identifier.new(:a)
+  #   Sequel.virtual_row{|o| o.a{}} # Sequel::SQL::Function.new(:a)
   def self.virtual_row(&block)
     vr = SQL::VirtualRow.new
     case block.arity