sequel 3.21.0 → 3.39.0

data/lib/sequel/extensions/eval_inspect.rb

@@ -0,0 +1,173 @@
+# The eval_inspect extension changes #inspect for Sequel::SQL::Expression
+# subclasses to return a string suitable for ruby's eval, such that
+#
+#   eval(obj.inspect) == obj
+#
+# is true.  The above code is true for most of ruby's simple classes such
+# as String, Integer, Float, and Symbol, but it's not true for classes such
+# as Time, Date, and BigDecimal.  Sequel attempts to handle situations where
+# instances of these classes are a component of a Sequel expression.
+#
+# To load the extension:
+#
+#   Sequel.extension :eval_inspect
+
+module Sequel
+  module EvalInspect
+    # Special case objects where inspect does not generally produce input
+    # suitable for eval.  Used by Sequel::SQL::Expression#inspect so that
+    # it can produce a string suitable for eval even if components of the
+    # expression have inspect methods that do not produce strings suitable
+    # for eval.
+    def eval_inspect(obj)
+      case obj
+      when Sequel::SQL::Blob, Sequel::LiteralString, Sequel::SQL::ValueList
+        "#{obj.class}.new(#{obj.inspect})"
+      when Array
+        "[#{obj.map{|o| eval_inspect(o)}.join(', ')}]"
+      when Hash
+        "{#{obj.map{|k, v| "#{eval_inspect(k)} => #{eval_inspect(v)}"}.join(', ')}}"
+      when Time
+        datepart = "%Y-%m-%dT" unless obj.is_a?(Sequel::SQLTime)
+        if RUBY_VERSION < '1.9'
+          # Time on 1.8 doesn't handle %N (or %z on Windows), manually set the usec value in the string
+          hours, mins = obj.utc_offset.divmod(3600)
+          mins /= 60
+          "#{obj.class}.parse(#{obj.strftime("#{datepart}%H:%M:%S.#{sprintf('%06i%+03i%02i', obj.usec, hours, mins)}").inspect})#{'.utc' if obj.utc?}"
+        else
+          "#{obj.class}.parse(#{obj.strftime("#{datepart}%T.%N%z").inspect})#{'.utc' if obj.utc?}"
+        end
+      when DateTime
+        # Ignore date of calendar reform
+        "DateTime.parse(#{obj.strftime('%FT%T.%N%z').inspect})"
+      when Date
+        # Ignore offset and date of calendar reform
+        "Date.new(#{obj.year}, #{obj.month}, #{obj.day})"
+      when BigDecimal
+        "BigDecimal.new(#{obj.to_s.inspect})"
+      else
+        obj.inspect
+      end
+    end
+  end
+
+  extend EvalInspect
+
+  module SQL
+    class Expression
+      # Attempt to produce a string suitable for eval, such that:
+      #
+      #   eval(obj.inspect) == obj
+      def inspect
+        # Assume by default that the object can be recreated by calling
+        # self.class.new with any attr_reader values defined on the class,
+        # in the order they were defined.
+        klass = self.class
+        args = inspect_args.map do |arg|
+          if arg.is_a?(String) && arg =~ /\A\*/
+            # Special case string arguments starting with *, indicating that
+            # they should return an array to be splatted as the remaining arguments
+            send(arg.sub('*', '')).map{|a| Sequel.eval_inspect(a)}.join(', ')
+          else
+            Sequel.eval_inspect(send(arg))
+          end
+        end
+        "#{klass}.new(#{args.join(', ')})"
+      end
+
+      private
+
+      # Which attribute values to use in the inspect string.
+      def inspect_args
+        self.class.comparison_attrs
+      end
+    end
+
+    class ComplexExpression
+      private
+
+      # ComplexExpression's initializer uses a splat for the operator arguments.
+      def inspect_args
+        [:op, "*args"]
+      end
+    end
+
+    class Constant
+      # Constants to lookup in the Sequel module.
+      INSPECT_LOOKUPS = [:CURRENT_DATE, :CURRENT_TIMESTAMP, :CURRENT_TIME, :SQLTRUE, :SQLFALSE, :NULL, :NOTNULL]
+
+      # Reference the constant in the Sequel module if there is
+      # one that matches.
+      def inspect
+        INSPECT_LOOKUPS.each do |c|
+          return "Sequel::#{c}" if Sequel.const_get(c) == self
+        end
+        super
+      end
+    end
+
+    class CaseExpression
+      private
+
+      # CaseExpression's initializer checks whether an argument was
+      # provided, to differentiate CASE WHEN from CASE NULL WHEN, so
+      # check if an expression was provided, and only include the
+      # expression in the inspect output if so.
+      def inspect_args
+        if expression?
+          [:conditions, :default, :expression]
+        else
+          [:conditions, :default]
+        end
+      end
+    end
+
+    class Function
+      private
+
+      # Function's initializer uses a splat for the function arguments.
+      def inspect_args
+        [:f, "*args"]
+      end
+    end
+
+    class JoinOnClause
+      private
+
+      # JoinOnClause's initializer takes the on argument as the first argument
+      # instead of the last.
+      def inspect_args
+        [:on, :join_type, :table, :table_alias] 
+      end
+    end
+
+    class JoinUsingClause
+      private
+
+      # JoinOnClause's initializer takes the using argument as the first argument
+      # instead of the last.
+      def inspect_args
+        [:using, :join_type, :table, :table_alias] 
+      end
+    end
+
+    class OrderedExpression
+      private
+
+      # OrderedExpression's initializer takes the :nulls information inside a hash,
+      # so if a NULL order was given, include a hash with that information.
+      def inspect_args
+        if nulls
+          [:expression, :descending, :opts_hash]
+        else
+          [:expression, :descending]
+        end
+      end
+
+      # A hash of null information suitable for passing to the initializer.
+      def opts_hash
+        {:nulls=>nulls} 
+      end
+    end
+  end
+end

data/lib/sequel/extensions/inflector.rb

@@ -2,6 +2,10 @@
 # words from singular to plural, class names to table names, modularized class
 # names to ones without, and class names to foreign keys.  It exists for 
 # backwards compatibility to legacy Sequel code.
+#
+# To load the extension:
+#
+#   Sequel.extension :inflector
 
 class String
   # This module acts as a singleton returned/yielded by String.inflections,

data/lib/sequel/extensions/looser_typecasting.rb

@@ -1,10 +1,8 @@
 # The LooserTypecasting extension changes the float and integer typecasting to
 # use the looser .to_f and .to_i instead of the more strict Kernel.Float and
-# Kernel.Integer.  To use it, you should extend the database with the
-# Sequel::LooserTypecasting module after loading the extension:
+# Kernel.Integer.  To load the extension into the database:
 #
-#   Sequel.extension :looser_typecasting
-#   DB.extend(Sequel::LooserTypecasting)
+#   DB.extension :looser_typecasting
 
 module Sequel
   module LooserTypecasting
@@ -18,4 +16,7 @@ module Sequel
       value.to_i
     end
   end
+
+  Database.register_extension(:looser_typecasting, LooserTypecasting)
 end
+

data/lib/sequel/extensions/migration.rb

@@ -1,6 +1,10 @@
 # Adds the Sequel::Migration and Sequel::Migrator classes, which allow
 # the user to easily group schema changes and migrate the database
 # to a newer version or revert to a previous version.
+#
+# To load the extension:
+#
+#   Sequel.extension :migration
 
 module Sequel
   # Sequel's older migration class, available for backward compatibility.
@@ -21,7 +25,7 @@ module Sequel
   #
   # Part of the +migration+ extension.
   class Migration
-    # Creates a new instance of the migration and sets the @db attribute.
+    # Set the database associated with this migration.
     def initialize(db)
       @db = db
     end
@@ -42,6 +46,11 @@ module Sequel
     def self.inherited(base)
       descendants << base
     end
+
+    # Don't allow transaction overriding in old migrations.
+    def self.use_transactions
+      nil
+    end
     
     # The default down action does nothing
     def down
@@ -68,6 +77,15 @@ module Sequel
     # Proc used for the up action
     attr_accessor :up
 
+    # Whether to use transactions for this migration, default depends on the
+    # database.
+    attr_accessor :use_transactions
+
+    # Don't set transaction use by default.
+    def initialize
+      @use_transactions = nil
+    end
+
     # Apply the appropriate block on the +Database+
     # instance using instance_eval.
     def apply(db, direction)
@@ -99,6 +117,16 @@ module Sequel
       migration.down = block
     end
 
+    # Disable the use of transactions for the related migration
+    def no_transaction
+      migration.use_transactions = false
+    end
+
+    # Enable the use of transactions for the related migration
+    def transaction
+      migration.use_transactions = true
+    end
+
     # Defines the migration's up action.
     def up(&block)
       migration.up = block
@@ -165,6 +193,10 @@ module Sequel
       @actions << [:alter_table, table, MigrationAlterTableReverser.new.reverse(&block)]
     end
 
+    def create_join_table(*args)
+      @actions << [:drop_join_table, *args]
+    end
+
     def create_table(*args)
       @actions << [:drop_table, args.first]
     end
@@ -302,7 +334,7 @@ module Sequel
   #
   # Part of the +migration+ extension.
   class Migrator
-    MIGRATION_FILE_PATTERN = /\A\d+_.+\.rb\z/i.freeze
+    MIGRATION_FILE_PATTERN = /\A(\d+)_.+\.rb\z/i.freeze
     MIGRATION_SPLITTER = '_'.freeze
     MINIMUM_TIMESTAMP = 20000101
 
@@ -311,11 +343,28 @@ module Sequel
     class Error < Sequel::Error
     end
 
+    # Exception class raised when Migrator.check_current signals that it is
+    # not current.
+    class NotCurrentError < Error
+    end
+
     # Wrapper for +run+, maintaining backwards API compatibility
     def self.apply(db, directory, target = nil, current = nil)
       run(db, directory, :target => target, :current => current)
     end
 
+    # Raise a NotCurrentError unless the migrator is current, takes the same
+    # arguments as #run.
+    def self.check_current(*args)
+      raise(NotCurrentError, 'migrator is not current') unless is_current?(*args)
+    end
+
+    # Return whether the migrator is current (i.e. it does not need to make
+    # any changes).  Takes the same arguments as #run.
+    def self.is_current?(db, directory, opts={})
+      migrator_class(directory).new(db, directory, opts).is_current?
+    end
+
     # Migrates the supplied database using the migration files in the the specified directory. Options:
     # * :column :: The column in the :table argument storing the migration version (default: :version).
     # * :current :: The current version of the database.  If not given, it is retrieved from the database
@@ -336,11 +385,15 @@ module Sequel
     # if the version number appears to be a unix time integer for a year
     # after 2005, otherwise uses the IntegerMigrator.
     def self.migrator_class(directory)
-      Dir.new(directory).each do |file|
-        next unless MIGRATION_FILE_PATTERN.match(file)
-        return TimestampMigrator if file.split(MIGRATION_SPLITTER, 2).first.to_i > MINIMUM_TIMESTAMP
+      if self.equal?(Migrator)
+        Dir.new(directory).each do |file|
+          next unless MIGRATION_FILE_PATTERN.match(file)
+          return TimestampMigrator if file.split(MIGRATION_SPLITTER, 2).first.to_i > MINIMUM_TIMESTAMP
+        end
+        IntegerMigrator
+      else
+        self
       end
-      IntegerMigrator
     end
     private_class_method :migrator_class
     
@@ -375,13 +428,35 @@ module Sequel
       @db = db
       @directory = directory
       @files = get_migration_files
-      @table = opts[:table]  || self.class.const_get(:DEFAULT_SCHEMA_TABLE)
+      schema, table = @db.send(:schema_and_table, opts[:table]  || self.class.const_get(:DEFAULT_SCHEMA_TABLE))
+      @table = schema ? Sequel::SQL::QualifiedIdentifier.new(schema, table) : table
       @column = opts[:column] || self.class.const_get(:DEFAULT_SCHEMA_COLUMN)
       @ds = schema_dataset
+      @use_transactions = opts[:use_transactions]
     end
 
     private
 
+    # If transactions should be used for the migration, yield to the block
+    # inside a transaction.  Otherwise, just yield to the block.
+    def checked_transaction(migration, &block)
+      use_trans = if @use_transactions.nil?
+        if migration.use_transactions.nil?
+          @db.supports_transactional_ddl?
+        else
+          migration.use_transactions
+        end
+      else
+        @use_transactions
+      end
+
+      if use_trans
+        db.transaction(&block)
+      else
+        yield
+      end
+    end
+
     # Remove all migration classes.  Done by the migrator to ensure that
     # the correct migration classes are picked up.
     def remove_migration_classes
@@ -423,19 +498,24 @@ module Sequel
       @current = opts[:current] || current_migration_version
 
       raise(Error, "No current version available") unless current
-      raise(Error, "No target version available") unless target
+      raise(Error, "No target version available, probably because no migration files found or filenames don't follow the migration filename convention") unless target
 
       @direction = current < target ? :up : :down
       @migrations = get_migrations
     end
 
+    # The integer migrator is current if the current version is the same as the target version.
+    def is_current?
+      current_migration_version == target
+    end
+    
     # Apply all migrations on the database
     def run
       migrations.zip(version_numbers).each do |m, v|
         t = Time.now
         lv = up? ? v : v + 1
         db.log_info("Begin applying migration version #{lv}, direction: #{direction}")
-        db.transaction do
+        checked_transaction(m) do
           m.apply(db, direction)
           set_migration_version(v)
         end
@@ -459,6 +539,9 @@ module Sequel
       Dir.new(directory).each do |file|
         next unless MIGRATION_FILE_PATTERN.match(file)
         version = migration_version_from_file(file)
+        if version >= 20000101
+          raise Migrator::Error, "Migration number too large, must use TimestampMigrator: #{file}"
+        end
         raise(Error, "Duplicate migration version: #{version}") if files[version]
         files[version] = File.join(directory, file)
       end
@@ -543,12 +626,18 @@ module Sequel
       @migration_tuples = get_migration_tuples
     end
 
+    # The timestamp migrator is current if there are no migrations to apply
+    # in either direction.
+    def is_current?
+      migration_tuples.empty?
+    end
+    
     # Apply all migration tuples on the database
     def run
       migration_tuples.each do |m, f, direction|
         t = Time.now
         db.log_info("Begin applying migration #{f}, direction: #{direction}")
-        db.transaction do
+        checked_transaction(m) do
           m.apply(db, direction)
           fi = f.downcase
           direction == :up ? ds.insert(column=>fi) : ds.filter(column=>fi).delete
@@ -588,7 +677,7 @@ module Sequel
         next unless MIGRATION_FILE_PATTERN.match(file)
         files << File.join(directory, file)
       end
-      files.sort
+      files.sort_by{|f| MIGRATION_FILE_PATTERN.match(File.basename(f))[1].to_i}
     end
     
     # Returns tuples of migration, filename, and direction

data/lib/sequel/extensions/named_timezones.rb

@@ -8,6 +8,10 @@
 # typecast_timezone=.  If a string is passed, it is converted to a
 # TZInfo::Timezone using TZInfo::Timezone.get.
 #
+# To load the extension:
+#
+#   Sequel.extension :named_timezones
+#
 # Let's say you have the database server in New York and the
 # application server in Los Angeles.  For historical reasons, data
 # is stored in local New York time, but the application server only
@@ -21,6 +25,11 @@
 # Then, before data is stored in the database, it is converted to New
 # York time.  When data is retrieved from the database, it is
 # converted to Los Angeles time.
+#
+# Note that typecasting from the database timezone to the application
+# timezone when fetching rows is dependent on the database adapter,
+# and only works on adapters where Sequel itself does the conversion.
+# It should work on mysql, postgres, sqlite, ibmdb, and jdbc.
 
 require 'tzinfo'
 

data/lib/sequel/extensions/null_dataset.rb

@@ -0,0 +1,94 @@
+# The null_dataset extension adds the Dataset#nullify method, which
+# returns a cloned dataset that will never issue a query to the
+# database.  It implements the null object pattern for datasets.
+#
+# To load the extension:
+#
+#   Sequel.extension :null_dataset
+#
+# The most common usage is probably in a method that must return
+# a dataset, where the method knows the dataset shouldn't return
+# anything.  With standard Sequel, you'd probably just add a
+# WHERE condition that is always false, but that still results
+# in a query being sent to the database, and can be overridden
+# using #unfiltered, the OR operator, or a UNION.
+#
+# Usage:
+#
+#   ds = DB[:items].nullify.where(:a=>:b).select(:c)
+#   ds.sql # => "SELECT c FROM items WHERE (a = b)"
+#   ds.all # => [] # no query sent to the database
+#
+# Note that there is one case where a null dataset will sent
+# a query to the database.  If you call #columns on a nulled
+# dataset and the dataset doesn't have an already cached
+# version of the columns, it will create a new dataset with
+# the same options to get the columns.
+
+module Sequel
+  class Dataset
+    module NullDataset
+      # Create a new dataset from the dataset (which won't
+      # be nulled) to get the columns if they aren't already cached.
+      def columns
+        @columns ||= db.dataset(@opts).columns
+      end
+
+      # Return 0 without sending a database query.
+      def delete
+        0
+      end
+
+      # Return self without sending a database query, never yielding.
+      def each
+        self
+      end
+
+      # Return nil without sending a database query, never yielding.
+      def fetch_rows(sql)
+        nil
+      end
+
+      # Return nil without sending a database query.
+      def insert(*)
+        nil
+      end
+
+      # Return nil without sending a database query.
+      def truncate
+        nil
+      end
+
+      # Return 0 without sending a database query.
+      def update(v={})
+        0
+      end
+
+      protected
+
+      # Return nil without sending a database query.
+      def _import(columns, values, opts)
+        nil
+      end
+
+      private
+
+      # Just in case these are called directly by some internal code,
+      # make them noops.  There's nothing we can do if the db
+      # is accessed directly to make a change, though.
+      (%w'_ddl _dui _insert' << '').each do |m|
+        class_eval("private; def execute#{m}(sql, opts={}) end", __FILE__, __LINE__)
+      end
+    end
+
+    # Return a cloned nullified dataset.
+    def nullify
+      clone.nullify!
+    end
+
+    # Nullify the current dataset
+    def nullify!
+      extend NullDataset
+    end
+  end
+end

data/lib/sequel/extensions/pagination.rb

@@ -1,6 +1,10 @@
 # The pagination extension adds the Sequel::Dataset#paginate and #each_page methods,
 # which return paginated (limited and offset) datasets with some helpful methods
 # that make creating a paginated display easier.
+#
+# To load the extension:
+#
+#   Sequel.extension :pagination
 
 module Sequel
   class Dataset