sequel 3.21.0 → 3.41.0

data/lib/sequel/database/misc.rb

@@ -1,13 +1,35 @@
 module Sequel
   class Database
     # ---------------------
-    # :section: Miscellaneous methods
+    # :section: 7 - Miscellaneous methods
     # These methods don't fit neatly into another category.
     # ---------------------
+    
+    # Hash of extension name symbols to callable objects to load the extension
+    # into the Database object (usually by extending it with a module defined
+    # in the extension).
+    EXTENSIONS = {}
+
+    # Register an extension callback for Database objects.  ext should be the
+    # extension name symbol, and mod should either be a Module that the
+    # database is extended with, or a callable object called with the database
+    # object.  If mod is not provided, a block can be provided and is treated
+    # as the mod object.
+    def self.register_extension(ext, mod=nil, &block)
+      if mod
+        raise(Error, "cannot provide both mod and block to Database.register_extension") if block
+        if mod.is_a?(Module)
+          block = proc{|db| db.extend(mod)}
+        else
+          block = mod
+        end
+      end
+      Sequel.synchronize{EXTENSIONS[ext] = block}
+    end
 
     # Converts a uri to an options hash. These options are then passed
     # to a newly created database object. 
-    def self.uri_to_options(uri) # :nodoc:
+    def self.uri_to_options(uri)
       { :user => uri.user,
         :password => uri.password,
         :host => uri.host,
@@ -19,12 +41,14 @@ module Sequel
     # The options hash for this database
     attr_reader :opts
     
+    # Set the timezone to use for this database, overridding <tt>Sequel.database_timezone</tt>.
+    attr_writer :timezone
+    
     # Constructs a new instance of a database connection with the specified
     # options hash.
     #
     # Accepts the following options:
-    # :default_schema :: The default schema to use, should generally be nil
-    # :disconnection_proc :: A proc used to disconnect the connection
+    # :default_schema :: The default schema to use, see #default_schema.
     # :identifier_input_method :: A string method symbol to call on identifiers going into the database
     # :identifier_output_method :: A string method symbol to call on identifiers coming from the database
     # :logger :: A specific logger to use
@@ -34,14 +58,12 @@ module Sequel
     # :single_threaded :: Whether to use a single-threaded connection pool
     # :sql_log_level :: Method to use to log SQL to a logger, :info by default.
     #
-    # All options given are also passed to the connection pool.  If a block
-    # is given, it is used as the connection_proc for the ConnectionPool.
+    # All options given are also passed to the connection pool.
     def initialize(opts = {}, &block)
       @opts ||= opts
       @opts = connection_pool_default_options.merge(@opts)
       @loggers = Array(@opts[:logger]) + Array(@opts[:loggers])
       self.log_warn_duration = @opts[:log_warn_duration]
-      @opts[:disconnection_proc] ||= proc{|conn| disconnect_connection(conn)}
       block ||= proc{|server| connect(server)}
       @opts[:servers] = {} if @opts[:servers].is_a?(String)
       @opts[:adapter_class] = self.class
@@ -50,14 +72,50 @@ module Sequel
       @schemas = {}
       @default_schema = @opts.fetch(:default_schema, default_schema_default)
       @prepared_statements = {}
-      @transactions = []
+      @transactions = {}
       @identifier_input_method = nil
       @identifier_output_method = nil
       @quote_identifiers = nil
+      @timezone = nil
+      @dataset_class = dataset_class_default
+      @cache_schema = typecast_value_boolean(@opts.fetch(:cache_schema, true))
+      @dataset_modules = []
       self.sql_log_level = @opts[:sql_log_level] ? @opts[:sql_log_level].to_sym : :info
-      @pool = ConnectionPool.get_pool(@opts, &block)
+      @pool = ConnectionPool.get_pool(self, @opts)
 
-      ::Sequel::DATABASES.push(self)
+      Sequel.synchronize{::Sequel::DATABASES.push(self)}
+    end
+
+    # If a transaction is not currently in process, yield to the block immediately.
+    # Otherwise, add the block to the list of blocks to call after the currently
+    # in progress transaction commits (and only if it commits).
+    # Options:
+    # :server :: The server/shard to use.
+    def after_commit(opts={}, &block)
+      raise Error, "must provide block to after_commit" unless block
+      synchronize(opts[:server]) do |conn|
+        if h = _trans(conn)
+          raise Error, "cannot call after_commit in a prepared transaction" if h[:prepare]
+          (h[:after_commit] ||= []) << block
+        else
+          yield
+        end
+      end
+    end
+    
+    # If a transaction is not currently in progress, ignore the block.
+    # Otherwise, add the block to the list of the blocks to call after the currently
+    # in progress transaction rolls back (and only if it rolls back).
+    # Options:
+    # :server :: The server/shard to use.
+    def after_rollback(opts={}, &block)
+      raise Error, "must provide block to after_rollback" unless block
+      synchronize(opts[:server]) do |conn|
+        if h = _trans(conn)
+          raise Error, "cannot call after_rollback in a prepared transaction" if h[:prepare]
+          (h[:after_rollback] ||= []) << block
+        end
+      end
     end
     
     # Cast the given type to a literal type
@@ -68,11 +126,52 @@ module Sequel
       type_literal(:type=>type)
     end
 
+    # Load an extension into the receiver.  In addition to requiring the extension file, this
+    # also modifies the database to work with the extension (usually extending it with a
+    # module defined in the extension file).  If no related extension file exists or the
+    # extension does not have specific support for Database objects, an Error will be raised.
+    # Returns self.
+    def extension(*exts)
+      Sequel.extension(*exts)
+      exts.each do |ext|
+        if pr = Sequel.synchronize{EXTENSIONS[ext]}
+          pr.call(self)
+        else
+          raise(Error, "Extension #{ext} does not have specific support handling individual databases")
+        end
+      end
+      self
+    end
+
+    # Convert the given timestamp from the application's timezone,
+    # to the databases's timezone or the default database timezone if
+    # the database does not have a timezone.
+    def from_application_timestamp(v)
+      Sequel.convert_output_timestamp(v, timezone)
+    end
+
+    # Whether the database uses a global namespace for the index.  If
+    # false, the indexes are going to be namespaced per table.
+    def global_index_namespace?
+      true
+    end
+
+    # Return true if already in a transaction given the options,
+    # false otherwise.  Respects the :server option for selecting
+    # a shard.
+    def in_transaction?(opts={})
+      synchronize(opts[:server]){|conn| !!_trans(conn)}
+    end
+
     # Returns a string representation of the database object including the
-    # class name and the connection URI (or the opts if the URI
-    # cannot be constructed).
+    # class name and connection URI and options used when connecting (if any).
     def inspect
-      "#<#{self.class}: #{(uri rescue opts).inspect}>" 
+      a = []
+      a << uri.inspect if uri
+      if (oo = opts[:orig_opts]) && !oo.empty?
+        a << oo.inspect
+      end
+      "#<#{self.class}: #{a.join(' ')}>"
     end
 
     # Proxy the literal call to the dataset.
@@ -84,12 +183,34 @@ module Sequel
       schema_utility_dataset.literal(v)
     end
 
+    # Synchronize access to the prepared statements cache.
+    def prepared_statement(name)
+      Sequel.synchronize{prepared_statements[name]}
+    end
+
     # Default serial primary key options, used by the table creation
     # code.
     def serial_primary_key_options
       {:primary_key => true, :type => Integer, :auto_increment => true}
     end
 
+    # Cache the prepared statement object at the given name.
+    def set_prepared_statement(name, ps)
+      Sequel.synchronize{prepared_statements[name] = ps}
+    end
+
+    # Whether the database supports CREATE TABLE IF NOT EXISTS syntax,
+    # false by default.
+    def supports_create_table_if_not_exists?
+      false
+    end
+
+    # Whether the database supports DROP TABLE IF EXISTS syntax,
+    # default is the same as #supports_create_table_if_not_exists?.
+    def supports_drop_table_if_exists?
+      supports_create_table_if_not_exists?
+    end
+
     # Whether the database and adapter support prepared transactions
     # (two-phase commit), false by default.
     def supports_prepared_transactions?
@@ -101,11 +222,34 @@ module Sequel
       false
     end
 
+    # Whether the database and adapter support savepoints inside prepared transactions
+    # (two-phase commit), default is false.
+    def supports_savepoints_in_prepared_transactions?
+      supports_prepared_transactions? && supports_savepoints?
+    end
+
     # Whether the database and adapter support transaction isolation levels, false by default.
     def supports_transaction_isolation_levels?
       false
     end
 
+    # Whether DDL statements work correctly in transactions, false by default.
+    def supports_transactional_ddl?
+      false
+    end
+
+    # The timezone to use for this database, defaulting to <tt>Sequel.database_timezone</tt>.
+    def timezone
+      @timezone || Sequel.database_timezone
+    end
+
+    # Convert the given timestamp to the application's timezone,
+    # from the databases's timezone or the default database timezone if
+    # the database does not have a timezone.
+    def to_application_timestamp(v)
+      Sequel.convert_timestamp(v, timezone)
+    end
+
     # Typecast the value to the given column_type. Calls
     # typecast_value_#{column_type} if the method exists,
     # otherwise returns the value.
@@ -121,29 +265,10 @@ module Sequel
       end
     end
     
-    # Returns the URI identifying the database, which may not be the
-    # same as the URI used when connecting.
-    # This method can raise an error if the database used options
-    # instead of a connection string, and will not include uri
-    # parameters.
-    #
-    #   Sequel.connect('postgres://localhost/db?user=billg').url
-    #   # => "postgres://billg@localhost/db"
+    # Returns the URI use to connect to the database.  If a URI
+    # was not used when connecting, returns nil.
     def uri
-      uri = URI::Generic.new(
-        adapter_scheme.to_s,
-        nil,
-        @opts[:host],
-        @opts[:port],
-        nil,
-        "/#{@opts[:database]}",
-        nil,
-        nil,
-        nil
-      )
-      uri.user = @opts[:user]
-      uri.password = @opts[:password] if uri.user
-      uri.to_s
+      opts[:uri]
     end
     
     # Explicit alias of uri for easier subclassing.
@@ -175,12 +300,17 @@ module Sequel
     def database_error_classes
       []
     end
+
+    # Return true if exception represents a disconnect error, false otherwise.
+    def disconnect_error?(exception, opts)
+      opts[:disconnect]
+    end
     
     # Convert the given exception to a DatabaseError, keeping message
     # and traceback.
     def raise_error(exception, opts={})
       if !opts[:classes] || Array(opts[:classes]).any?{|c| exception.is_a?(c)}
-        raise Sequel.convert_exception_class(exception, opts[:disconnect] ? DatabaseDisconnectError : DatabaseError)
+        raise Sequel.convert_exception_class(exception, disconnect_error?(exception, opts) ? DatabaseDisconnectError : DatabaseError)
       else
         raise exception
       end
@@ -194,7 +324,7 @@ module Sequel
     # Typecast the value to true, false, or nil
     def typecast_value_boolean(value)
       case value
-      when false, 0, "0", /\Af(alse)?\z/i
+      when false, 0, "0", /\Af(alse)?\z/i, /\Ano?\z/i
         false
       else
         blank_object?(value) ? nil : true
@@ -204,10 +334,10 @@ module Sequel
     # Typecast the value to a Date
     def typecast_value_date(value)
       case value
-      when Date
-        value
       when DateTime, Time
         Date.new(value.year, value.month, value.day)
+      when Date
+        value
       when String
         Sequel.string_to_date(value)
       when Hash
@@ -219,12 +349,7 @@ module Sequel
 
     # Typecast the value to a DateTime or Time depending on Sequel.datetime_class
     def typecast_value_datetime(value)
-      klass = Sequel.datetime_class
-      if value.is_a?(Hash)
-        klass.send(klass == Time ? :mktime : :new, *[:year, :month, :day, :hour, :minute, :second].map{|x| (value[x] || value[x.to_s]).to_i})
-      else
-        Sequel.typecast_to_application_timestamp(value)
-      end
+      Sequel.typecast_to_application_timestamp(value)
     end
 
     # Typecast the value to a BigDecimal
@@ -244,9 +369,21 @@ module Sequel
       Float(value)
     end
 
-    # Typecast the value to an Integer
-    def typecast_value_integer(value)
-      Integer(value)
+    # Used for checking/removing leading zeroes from strings so they don't get
+    # interpreted as octal.
+    LEADING_ZERO_RE = /\A0+(\d)/.freeze
+    if RUBY_VERSION >= '1.9'
+      # Typecast the value to an Integer
+      def typecast_value_integer(value)
+        (value.is_a?(String) && value =~ LEADING_ZERO_RE) ? Integer(value, 10) : Integer(value)
+      end
+    else
+      # Replacement string when replacing leading zeroes.
+      LEADING_ZERO_REP = "\\1".freeze 
+      # Typecast the value to an Integer
+      def typecast_value_integer(value)
+        Integer(value.is_a?(String) ? value.sub(LEADING_ZERO_RE, LEADING_ZERO_REP) : value)
+      end
     end
 
     # Typecast the value to a String
@@ -258,12 +395,16 @@ module Sequel
     def typecast_value_time(value)
       case value
       when Time
-        value
+        if value.is_a?(SQLTime)
+          value
+        else
+          # specifically check for nsec == 0 value to work around JRuby 1.6 ruby 1.9 mode bug
+          SQLTime.create(value.hour, value.min, value.sec, (value.respond_to?(:nsec) && value.nsec != 0) ? value.nsec/1000.0 : value.usec)
+        end
       when String
         Sequel.string_to_time(value)
       when Hash
-        t = Time.now
-        Time.mktime(t.year, t.month, t.day, *[:hour, :minute, :second].map{|x| (value[x] || value[x.to_s]).to_i})
+        SQLTime.create(*[:hour, :minute, :second].map{|x| (value[x] || value[x.to_s]).to_i})
       else
         raise Sequel::InvalidValue, "invalid value for Time: #{value.inspect}"
       end