sequel 3.21.0 → 3.36.0

data/lib/sequel/dataset.rb

@@ -26,6 +26,14 @@ module Sequel
     extend Metaprogramming
     include Metaprogramming
     include Enumerable
+    include SQL::AliasMethods
+    include SQL::BooleanMethods
+    include SQL::CastMethods
+    include SQL::ComplexExpressionMethods
+    include SQL::InequalityMethods
+    include SQL::NumericMethods
+    include SQL::OrderMethods
+    include SQL::StringMethods
   end
   
   require(%w"query actions features graph prepared_statements misc mutation sql", 'dataset')

data/lib/sequel/exceptions.rb

@@ -44,6 +44,10 @@ module Sequel
   # and won't reraise it.
   class Rollback < Error ; end
 
+  # Exception that occurs when unbinding a dataset that has multiple different values
+  # for a given variable.
+  class UnbindDuplicate < Error; end
+
   class Error
     AdapterNotFound = Sequel::AdapterNotFound
     InvalidOperation = Sequel::InvalidOperation

data/lib/sequel/extensions/_pretty_table.rb

@@ -0,0 +1,79 @@
+# The pretty_table extension adds Sequel::Dataset#print and the
+# Sequel::PrettyTable class for creating nice-looking plain-text
+# tables.
+
+module Sequel
+  module PrettyTable
+    # Prints nice-looking plain-text tables via puts
+    # 
+    #   +--+-------+
+    #   |id|name   |
+    #   |--+-------|
+    #   |1 |fasdfas|
+    #   |2 |test   |
+    #   +--+-------+
+    def self.print(records, columns=nil)
+      puts string(records, columns)
+    end
+
+    # Return the string that #print will print via puts.
+    def self.string(records, columns = nil) # records is an array of hashes
+      columns ||= records.first.keys.sort_by{|x|x.to_s}
+      sizes = column_sizes(records, columns)
+      sep_line = separator_line(columns, sizes)
+
+      array = [sep_line, header_line(columns, sizes), sep_line]
+      records.each {|r| array << data_line(columns, sizes, r)}
+      array << sep_line
+      array.join("\n")
+    end
+
+    ### Private Module Methods ###
+
+    # Hash of the maximum size of the value for each column 
+    def self.column_sizes(records, columns) # :nodoc:
+      sizes = Hash.new {0}
+      columns.each do |c|
+        s = c.to_s.size
+        sizes[c.to_sym] = s if s > sizes[c.to_sym]
+      end
+      records.each do |r|
+        columns.each do |c|
+          s = r[c].to_s.size
+          sizes[c.to_sym] = s if s > sizes[c.to_sym]
+        end
+      end
+      sizes
+    end
+    
+    # String for each data line
+    def self.data_line(columns, sizes, record) # :nodoc:
+      '|' << columns.map {|c| format_cell(sizes[c], record[c])}.join('|') << '|'
+    end
+    
+    # Format the value so it takes up exactly size characters
+    def self.format_cell(size, v) # :nodoc:
+      case v
+      when Bignum, Fixnum
+        "%#{size}d" % v
+      when Float
+        "%#{size}g" % v
+      else
+        "%-#{size}s" % v.to_s
+      end
+    end
+    
+    # String for header line
+    def self.header_line(columns, sizes) # :nodoc:
+      '|' << columns.map {|c| "%-#{sizes[c]}s" % c.to_s}.join('|') << '|'
+    end
+
+    # String for separtor line
+    def self.separator_line(columns, sizes) # :nodoc:
+      '+' << columns.map {|c| '-' * sizes[c]}.join('+') << '+'
+    end
+
+    private_class_method :column_sizes, :data_line, :format_cell, :header_line, :separator_line
+  end
+end
+

data/lib/sequel/extensions/arbitrary_servers.rb

@@ -0,0 +1,108 @@
+# The arbitrary_servers extension allows you to connect to arbitrary
+# servers/shards that were not defined when you created the database.
+# To use it, you first extend the Database's connection pool with the
+# Sequel::ArbitraryServers module:
+#
+#   Sequel.extension :arbitrary_servers
+#   DB.pool.extend Sequel::ArbitraryServers
+#
+# Then you can pass arbitrary connection options for the server/shard
+# to use as a hash:
+#
+#   DB[:table].server(:host=>'...', :database=>'...').all
+#
+# Because Sequel can never be sure that the connection will be reused,
+# arbitrary connections are disconnected as soon as the outermost block
+# that uses them exits.  So this example uses the same connection:
+#
+#   DB.transaction(:server=>{:host=>'...', :database=>'...'}) do |c|
+#     DB.transaction(:server=>{:host=>'...', :database=>'...'}) do |c2|
+#       # c == c2
+#     end
+#   end
+#
+# But this example does not:
+#
+#   DB.transaction(:server=>{:host=>'...', :database=>'...'}) do |c|
+#   end
+#   DB.transaction(:server=>{:host=>'...', :database=>'...'}) do |c2|
+#     # c != c2
+#   end
+#
+# You can use this extension in conjunction with the server_block
+# extension:
+#
+#   DB.with_server(:host=>'...', :database=>'...') do
+#     DB.synchronize do
+#       # All of these use the host/database given to with_server
+#       DB[:table].insert(...)
+#       DB[:table].update(...)
+#       DB.tables
+#       DB[:table].all
+#     end
+#   end
+#
+# Anyone using this extension in conjunction with the server_block
+# extension may want to do the following to so that you don't need
+# to call synchronize separately:
+#
+#   def DB.with_server(*)
+#     super{synchronize{yield}}
+#   end
+#
+# Note that this extension only works with the sharded threaded connection
+# pool.  If you are using the sharded single connection pool, you need
+# to switch to the sharded threaded connection pool before using this
+# extension.
+
+module Sequel
+  module ArbitraryServers
+    private
+
+    # If server is a hash, create a new connection for
+    # it, and cache it first by thread and then server.
+    def acquire(thread, server)
+      if server.is_a?(Hash)
+        sync{@allocated[thread] ||= {}}[server] = make_new(server)
+      else
+        super
+      end
+    end
+    
+    # If server is a hash, the entry for it probably doesn't
+    # exist in the @allocated hash, so check for existence to
+    # avoid calling nil.[]
+    def owned_connection(thread, server)
+      if server.is_a?(Hash)
+        if a = sync{@allocated[thread]}
+          a[server]
+        end
+      else
+        super
+      end
+    end
+
+    # If server is a hash, return it directly.
+    def pick_server(server)
+      if server.is_a?(Hash)
+        server
+      else
+        super
+      end
+    end
+
+    # If server is a hash, delete the thread from the allocated
+    # connections for that server.  Additionally, if this was the last thread
+    # using that server, delete the server from the @allocated hash.
+    def release(thread, conn, server)
+      if server.is_a?(Hash)
+        a = @allocated[thread]
+        a.delete(server)
+        @allocated.delete(thread) if a.empty?
+        @disconnection_proc.call(conn) if @disconnection_proc
+      else  
+        super
+      end
+    end
+  end
+end

data/lib/sequel/extensions/columns_introspection.rb

@@ -0,0 +1,61 @@
+# The columns_introspection extension attempts to introspect the
+# selected columns for a dataset before issuing a query.  If it
+# thinks it can guess correctly at the columns the query will use,
+# it will return the columns without issuing a database query.
+# This method is not fool-proof, it's possible that some databases
+# will use column names that Sequel does not expect.
+#
+# To enable this for a single dataset, extend the dataset with
+# Sequel::ColumnIntrospection.  To enable this for all datasets, run:
+#
+#   Sequel::Dataset.introspect_all_columns
+
+module Sequel
+  module ColumnsIntrospection
+    # Attempt to guess the columns that will be returned
+    # if there are columns selected, in order to skip a database
+    # query to retrieve the columns.  This should work with
+    # Symbols, SQL::Identifiers, SQL::QualifiedIdentifiers, and
+    # SQL::AliasedExpressions.
+    def columns
+      return @columns if @columns
+      return columns_without_introspection unless cols = opts[:select] and !cols.empty?
+      probable_columns = cols.map{|c| probable_column_name(c)}
+      if probable_columns.all?
+        @columns = probable_columns
+      else
+        columns_without_introspection
+      end
+    end
+
+    private
+
+    # Return the probable name of the column, or nil if one
+    # cannot be determined.
+    def probable_column_name(c)
+      case c
+      when Symbol
+        _, c, a = split_symbol(c)
+        (a || c).to_sym
+      when SQL::Identifier
+        c.value.to_sym
+      when SQL::QualifiedIdentifier
+        col = c.column
+        col.is_a?(SQL::Identifier) ? col.value.to_sym : col.to_sym
+      when SQL::AliasedExpression
+        a = c.aliaz
+        a.is_a?(SQL::Identifier) ? a.value.to_sym : a.to_sym
+      end
+    end
+  end
+
+  class Dataset
+    alias columns_without_introspection columns
+
+    # Enable column introspection for every dataset.
+    def self.introspect_all_columns
+      include ColumnsIntrospection
+      remove_method(:columns) if instance_methods(false).map{|x| x.to_s}.include?('columns')
+    end
+  end
+end

data/lib/sequel/{core_sql.rb → extensions/core_extensions.rb}

@@ -1,3 +1,13 @@
+# These are extensions to core classes that Sequel enables by default.
+# They make using Sequel's DSL easier by adding methods to Array,
+# Hash, String, and Symbol to add methods that return Sequel
+# expression objects.
+
+# This extension loads the core extensions.
+def Sequel.core_extensions?
+  true
+end
+
 # 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.
@@ -8,20 +18,7 @@ class Array
   #   ~[[:a, true]] # SQL: a IS NOT TRUE
   #   ~[[:a, 1], [:b, [2, 3]]] # SQL: a != 1 OR b NOT IN (2, 3)
   def ~
-    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
-  # could be a specifier of conditions, used similarly to a hash
-  # but allowing for duplicate keys and a specific order.
-  #
-  #    [].to_a.all_two_pairs? # => false
-  #    [:a].to_a.all_two_pairs? # => false
-  #    [[:b]].to_a.all_two_pairs? # => false
-  #    [[:a, 1]].to_a.all_two_pairs? # => true
-  def all_two_pairs?
-    !empty? && all?{|i| (Array === i) && (i.length == 2)}
+    Sequel.~(self)
   end
 
   # Return a <tt>Sequel::SQL::CaseExpression</tt> with this array as the conditions and the given
@@ -59,7 +56,7 @@ class Array
   #   [[:a, true]].sql_expr # SQL: a IS TRUE
   #   [[:a, 1], [:b, [2, 3]]].sql_expr # SQL: a = 1 AND b IN (2, 3)
   def sql_expr
-    sql_expr_if_all_two_pairs
+    Sequel.expr(self)
   end
 
   # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this array, matching none
@@ -68,7 +65,7 @@ class Array
   #   [[:a, true]].sql_negate # SQL: a IS NOT TRUE
   #   [[:a, 1], [:b, [2, 3]]].sql_negate # SQL: a != 1 AND b NOT IN (2, 3)
   def sql_negate
-    sql_expr_if_all_two_pairs(:AND, true)
+    Sequel.negate(self)
   end
 
   # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this array, matching any of the
@@ -77,10 +74,10 @@ class Array
   #   [[:a, true]].sql_or # SQL: a IS TRUE
   #   [[:a, 1], [:b, [2, 3]]].sql_or # SQL: a = 1 OR b IN (2, 3)
   def sql_or
-    sql_expr_if_all_two_pairs(:OR)
+    Sequel.or(self)
   end
 
-  # Return a <tt>Sequel::SQL::BooleanExpression</tt> representing an SQL string made up of the
+  # Return a <tt>Sequel::SQL::StringExpression</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.
@@ -90,22 +87,7 @@ class Array
   #   [:a, 'b'].sql_string_join # SQL: a || 'b'
   #   ['a', :b].sql_string_join(' ') # SQL: 'a' || ' ' || b
   def sql_string_join(joiner=nil)
-    if joiner
-      args = zip([joiner]*length).flatten
-      args.pop
-    else
-      args = self
-    end
-    args = args.collect{|a| [Symbol, ::Sequel::SQL::Expression, ::Sequel::LiteralString, TrueClass, FalseClass, NilClass].any?{|c| a.is_a?(c)} ? a : a.to_s}
-    ::Sequel::SQL::StringExpression.new(:'||', *args)
-  end
-
-  private
-
-  # 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)
+    Sequel.join(self, joiner)
   end
 end
 

data/lib/sequel/extensions/migration.rb

@@ -2,6 +2,7 @@
 # the user to easily group schema changes and migrate the database
 # to a newer version or revert to a previous version.
 
+#
 module Sequel
   # Sequel's older migration class, available for backward compatibility.
   # Uses subclasses with up and down instance methods for each migration:
@@ -21,7 +22,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 +43,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 +74,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 +114,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 +190,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 +331,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 +340,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 +382,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 +425,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 +495,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 +536,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 +623,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 +674,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

@@ -21,6 +21,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,90 @@
+# 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.
+#
+# 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