sequel 3.21.0 → 3.31.0

data/lib/sequel/database/query.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Database
     # ---------------------
-    # :section: Methods that execute queries and/or return results
+    # :section: 1 - Methods that execute queries and/or return results
     # This methods generally execute SQL code on the database server.
     # ---------------------
 
@@ -37,9 +37,12 @@ module Sequel
     attr_accessor :transaction_isolation_level
     
     # Runs the supplied SQL statement string on the database server.
-    # Alias for run.
+    # Returns self so it can be safely chained:
+    #
+    #   DB << "UPADTE albums SET artist_id = NULL" << "DROP TABLE artists"
     def <<(sql)
       run(sql)
+      self
     end
     
     # Call the prepared statement with the given name with the given hash
@@ -82,12 +85,12 @@ module Sequel
     #
     #   DB.get(1) # SELECT 1
     #   # => 1
-    #   DB.get{version{}} # SELECT server_version()
+    #   DB.get{server_version{}} # SELECT server_version()
     def get(*args, &block)
       dataset.get(*args, &block)
     end
     
-    # Return a hash containing index information. Hash keys are index name symbols.
+    # Return a hash containing index information for the table. Hash keys are index name symbols.
     # Values are subhashes with two keys, :columns and :unique.  The value of :columns
     # is an array of symbols of column names.  The value of :unique is true or false
     # depending on if the index is unique.
@@ -110,17 +113,17 @@ module Sequel
       nil
     end
     
-    # Parse the schema from the database.
     # Returns the schema for the given table as an array with all members being arrays of length 2,
     # the first member being the column name, and the second member being a hash of column information.
+    # The table argument can also be a dataset, as long as it only has one table.
     # Available options are:
     #
     # :reload :: Ignore any cached results, and get fresh information from the database.
     # :schema :: An explicit schema to use.  It may also be implicitly provided
     #            via the table name.
     #
-    # If schema parsing is supported by the database, the column information should at least contain the
-    # following columns:
+    # If schema parsing is supported by the database, the column information should hash at least contain the
+    # following entries:
     #
     # :allow_null :: Whether NULL is an allowed value for the column.
     # :db_type :: The database type for the column, as a database specific string.
@@ -129,7 +132,8 @@ module Sequel
     #                 it means that primary key information is unavailable, not that the column
     #                 is not a primary key.
     # :ruby_default :: The database default for the column, as a ruby object.  In many cases, complex
-    #                  database defaults cannot be parsed into ruby objects.
+    #                  database defaults cannot be parsed into ruby objects, in which case nil will be
+    #                  used as the value.
     # :type :: A symbol specifying the type, such as :integer or :string.
     #
     # Example:
@@ -152,9 +156,20 @@ module Sequel
     def schema(table, opts={})
       raise(Error, 'schema parsing is not implemented on this database') unless respond_to?(:schema_parse_table, true)
 
-      sch, table_name = schema_and_table(table)
-      quoted_name = quote_schema_table(table)
-      opts = opts.merge(:schema=>sch) if sch && !opts.include?(:schema)
+      opts = opts.dup
+      if table.is_a?(Dataset)
+        o = table.opts
+        from = o[:from]
+        raise(Error, "can only parse the schema for a dataset with a single from table") unless from && from.length == 1 && !o.include?(:join) && !o.include?(:sql)
+        tab = table.first_source_table
+        sch, table_name = schema_and_table(tab)
+        quoted_name = table.literal(tab)
+        opts[:dataset] = table
+      else
+        sch, table_name = schema_and_table(table)
+        quoted_name = quote_schema_table(table)
+      end
+      opts[:schema] = sch if sch && !opts.include?(:schema)
 
       @schemas.delete(quoted_name) if opts[:reload]
       return @schemas[quoted_name] if @schemas[quoted_name]
@@ -169,13 +184,14 @@ module Sequel
     # to the database.
     #
     #   DB.table_exists?(:foo) # => false
+    #   # SELECT * FROM foo LIMIT 1
     def table_exists?(name)
-      begin 
-        from(name).first
-        true
-      rescue
-        false
-      end
+      sch, table_name = schema_and_table(name)
+      name = SQL::QualifiedIdentifier.new(sch, table_name) if sch
+      from(name).first
+      true
+    rescue
+      false
     end
     
     # Return all tables in the database as an array of symbols.
@@ -198,6 +214,9 @@ module Sequel
     # :prepare :: A string to use as the transaction identifier for a
     #             prepared transaction (two-phase commit), if the database/adapter
     #             supports prepared transactions.
+    # :rollback :: Can the set to :reraise to reraise any Sequel::Rollback exceptions
+    #              raised, or :always to always rollback even if no exceptions occur
+    #              (useful for testing).
     # :server :: The server to use for the transaction.
     # :savepoint :: Whether to create a new savepoint for this transaction,
     #               only respected if the database/adapter supports savepoints.  By
@@ -210,6 +229,13 @@ module Sequel
       end
     end
     
+    # Return all views in the database as an array of symbols.
+    #
+    #   DB.views # => [:gold_albums, :artists_with_many_albums]
+    def views(opts={})
+      raise NotImplemented, "#views should be overridden by adapters"
+    end
+    
     private
     
     # Internal generic transaction method.  Any exception raised by the given
@@ -217,40 +243,65 @@ module Sequel
     # not a Sequel::Rollback, the error will be reraised. If no exception occurs
     # inside the block, the transaction is commited.
     def _transaction(conn, opts={})
+      rollback = opts[:rollback]
       begin
-        add_transaction
-        t = begin_transaction(conn, opts)
-        yield(conn)
+        add_transaction(conn, opts)
+        begin_transaction(conn, opts)
+        if rollback == :always
+          begin
+            yield(conn)
+          rescue Exception => e1
+            raise e1
+          ensure
+            raise ::Sequel::Rollback unless e1
+          end
+        else
+          yield(conn)
+        end
       rescue Exception => e
-        rollback_transaction(t, opts) if t
-        transaction_error(e)
+        rollback_transaction(conn, opts)
+        transaction_error(e, :conn=>conn, :rollback=>rollback)
       ensure
         begin
-          commit_transaction(t, opts) unless e
-        rescue Exception => e
-          raise_error(e, :classes=>database_error_classes)
+          committed = commit_or_rollback_transaction(e, conn, opts)
+        rescue Exception => e2
+          raise_error(e2, :classes=>database_error_classes, :conn=>conn)
         ensure
-          remove_transaction(t)
+          remove_transaction(conn, committed)
         end
       end
     end
-    
+
     # Add the current thread to the list of active transactions
-    def add_transaction
-      th = Thread.current
+    def add_transaction(conn, opts)
       if supports_savepoints?
-        unless @transactions.include?(th)
-          th[:sequel_transaction_depth] = 0
-          @transactions << th
+        unless @transactions[conn]
+          @transactions[conn] = {:savepoint_level=>0}
+          @transactions[conn][:prepare] = opts[:prepare] if supports_prepared_transactions?
         end
       else
-        @transactions << th
+        @transactions[conn] = {}
+        @transactions[conn][:prepare] = opts[:prepare] if supports_prepared_transactions?
       end
     end    
 
+    # Call all stored after_commit blocks for the given transaction
+    def after_transaction_commit(conn)
+      if ary = @transactions[conn][:after_commit]
+        ary.each{|b| b.call}
+      end
+    end
+
+    # Call all stored after_rollback blocks for the given transaction
+    def after_transaction_rollback(conn)
+      if ary = @transactions[conn][:after_rollback]
+        ary.each{|b| b.call}
+      end
+    end
+
     # Whether the current thread/connection is already inside a transaction
     def already_in_transaction?(conn, opts)
-      @transactions.include?(Thread.current) && (!supports_savepoints? || !opts[:savepoint])
+      @transactions.has_key?(conn) && (!supports_savepoints? || !opts[:savepoint])
     end
     
     # SQL to start a new savepoint
@@ -267,17 +318,16 @@ module Sequel
     # Start a new database transaction or a new savepoint on the given connection.
     def begin_transaction(conn, opts={})
       if supports_savepoints?
-        th = Thread.current
-        if (depth = th[:sequel_transaction_depth]) > 0
+        th = @transactions[conn]
+        if (depth = th[:savepoint_level]) > 0
           log_connection_execute(conn, begin_savepoint_sql(depth))
         else
           begin_new_transaction(conn, opts)
         end
-        th[:sequel_transaction_depth] += 1
+        th[:savepoint_level] += 1
       else
         begin_new_transaction(conn, opts)
       end
-      conn
     end
     
     # SQL to BEGIN a transaction.
@@ -335,6 +385,38 @@ module Sequel
       end
     end
    
+    if (! defined?(RUBY_ENGINE) or RUBY_ENGINE == 'ruby' or RUBY_ENGINE == 'rbx') and RUBY_VERSION < '1.9'
+      # Whether to commit the current transaction. On ruby 1.8 and rubinius,
+      # Thread.current.status is checked because Thread#kill skips rescue
+      # blocks (so exception would be nil), but the transaction should
+      # still be rolled back.
+      def commit_or_rollback_transaction(exception, conn, opts)
+        if exception
+          false
+        else
+          if Thread.current.status == 'aborting'
+            rollback_transaction(conn, opts)
+            false
+          else
+            commit_transaction(conn, opts)
+            true
+          end
+        end
+      end
+    else
+      # Whether to commit the current transaction.  On ruby 1.9 and JRuby,
+      # transactions will be committed if Thread#kill is used on an thread
+      # that has a transaction open, and there isn't a work around.
+      def commit_or_rollback_transaction(exception, conn, opts)
+        if exception
+          false
+        else
+          commit_transaction(conn, opts)
+          true
+        end
+      end
+    end
+    
     # SQL to commit a savepoint
     def commit_savepoint_sql(depth)
       SQL_RELEASE_SAVEPOINT % depth
@@ -343,7 +425,7 @@ module Sequel
     # Commit the active transaction on the connection
     def commit_transaction(conn, opts={})
       if supports_savepoints?
-        depth = Thread.current[:sequel_transaction_depth]
+        depth = @transactions[conn][:savepoint_level]
         log_connection_execute(conn, depth > 1 ? commit_savepoint_sql(depth-1) : commit_transaction_sql)
       else
         log_connection_execute(conn, commit_transaction_sql)
@@ -364,8 +446,8 @@ module Sequel
     # Return a Method object for the dataset's output_identifier_method.
     # Used in metadata parsing to make sure the returned information is in the
     # correct format.
-    def input_identifier_meth
-      dataset.method(:input_identifier)
+    def input_identifier_meth(ds=nil)
+      (ds || dataset).method(:input_identifier)
     end
     
     # Return a dataset that uses the default identifier input and output methods
@@ -382,24 +464,28 @@ module Sequel
     # Return a Method object for the dataset's output_identifier_method.
     # Used in metadata parsing to make sure the returned information is in the
     # correct format.
-    def output_identifier_meth
-      dataset.method(:output_identifier)
+    def output_identifier_meth(ds=nil)
+      (ds || dataset).method(:output_identifier)
     end
 
-    # SQL to ROLLBACK a transaction.
-    def rollback_transaction_sql
-      SQL_ROLLBACK
-    end
-    
     # Remove the cached schema for the given schema name
     def remove_cached_schema(table)
       @schemas.delete(quote_schema_table(table)) if @schemas
     end
     
     # Remove the current thread from the list of active transactions
-    def remove_transaction(conn)
-      th = Thread.current
-      @transactions.delete(th) if !supports_savepoints? || ((th[:sequel_transaction_depth] -= 1) <= 0)
+    def remove_transaction(conn, committed)
+      if !supports_savepoints? || ((@transactions[conn][:savepoint_level] -= 1) <= 0)
+        begin
+          if committed
+            after_transaction_commit(conn)
+          else
+            after_transaction_rollback(conn)
+          end
+        ensure
+          @transactions.delete(conn)
+        end
+      end
     end
 
     # SQL to rollback to a savepoint
@@ -410,13 +496,18 @@ module Sequel
     # Rollback the active transaction on the connection
     def rollback_transaction(conn, opts={})
       if supports_savepoints?
-        depth = Thread.current[:sequel_transaction_depth]
+        depth = @transactions[conn][:savepoint_level]
         log_connection_execute(conn, depth > 1 ? rollback_savepoint_sql(depth-1) : rollback_transaction_sql)
       else
         log_connection_execute(conn, rollback_transaction_sql)
       end
     end
 
+    # SQL to ROLLBACK a transaction.
+    def rollback_transaction_sql
+      SQL_ROLLBACK
+    end
+    
     # Match the database's column type to a ruby type via a
     # regular expression, and return the ruby type as a symbol
     # such as :integer or :string.
@@ -434,13 +525,13 @@ module Sequel
         :datetime
       when /\Atime( with(out)? time zone)?\z/io
         :time
-      when /\A(boolean|bit)\z/io
+      when /\A(bool(ean)?)\z/io
         :boolean
       when /\A(real|float|double( precision)?)\z/io
         :float
-      when /\A(?:(?:(?:num(?:ber|eric)?|decimal)(?:\(\d+,\s*(\d+)\))?)|(?:small)?money)\z/io
-        $1 && $1 == '0' ? :integer : :decimal
-      when /bytea|blob|image|(var)?binary/io
+      when /\A(?:(?:(?:num(?:ber|eric)?|decimal)(?:\(\d+,\s*(\d+|false|true)\))?)|(?:small)?money)\z/io
+        $1 && ['0', 'false'].include?($1) ? :integer : :decimal
+      when /bytea|[bc]lob|image|(var)?binary/io
         :blob
       when /\Aenum/io
         :enum
@@ -460,8 +551,12 @@ module Sequel
     end
 
     # Raise a database error unless the exception is an Rollback.
-    def transaction_error(e)
-      raise_error(e, :classes=>database_error_classes) unless e.is_a?(Rollback)
+    def transaction_error(e, opts={})
+      if e.is_a?(Rollback)
+        raise e if opts[:rollback] == :reraise
+      else
+        raise_error(e, opts.merge(:classes=>database_error_classes))
+      end
     end
   end
 end

data/lib/sequel/database/schema_generator.rb

@@ -86,7 +86,8 @@ module Sequel
       # :index :: Create an index on this column.
       # :key :: For foreign key columns, the column in the associated table
       #         that this column references.  Unnecessary if this column
-      #         references the primary key of the associated table.
+      #         references the primary key of the associated table, except if you are
+      #         using MySQL.
       # :null :: Mark the column as allowing NULL values (if true),
       #          or not allowing NULL values (if false).  If unspecified, will default
       #          to whatever the database default is.
@@ -124,6 +125,13 @@ module Sequel
       #   foreign_key(:artist_id) # artist_id INTEGER
       #   foreign_key(:artist_id, :artists) # artist_id INTEGER REFERENCES artists
       #   foreign_key(:artist_id, :artists, :key=>:id) # artist_id INTEGER REFERENCES artists(id)
+      #
+      # If you want a foreign key constraint without adding a column (usually because it is a
+      # composite foreign key), you can provide an array of columns as the first argument, and
+      # you can provide the :name option to name the constraint:
+      #
+      #   foreign_key([:artist_name, :artist_location], :artists, :name=>:artist_fk)
+      #   # ADD CONSTRAINT artist_fk FOREIGN KEY (artist_name, artist_location) REFERENCES artists
       def foreign_key(name, table=nil, opts = {})
         opts = case table
         when Hash
@@ -281,8 +289,8 @@ module Sequel
       # to the DDL for the table.  See Generator#column for the available options.
       #
       # You can also pass an array of column names for creating composite foreign
-      # keys. In this case, it will assume the columns exists and will only add
-      # the constraint.
+      # keys. In this case, it will assume the columns exist and will only add
+      # the constraint.  You can provide a :name option to name the constraint.
       #
       # NOTE: If you need to add a foreign key constraint to a single existing column
       # use the composite key syntax even if it is only one column.
@@ -329,15 +337,17 @@ module Sequel
       # Remove a column from the DDL for the table.
       #
       #   drop_column(:artist_id) # DROP COLUMN artist_id
-      def drop_column(name)
-        @operations << {:op => :drop_column, :name => name}
+      #   drop_column(:artist_id, :cascade=>true) # DROP COLUMN artist_id CASCADE
+      def drop_column(name, opts={})
+        @operations << {:op => :drop_column, :name => name}.merge(opts)
       end
       
       # Remove a constraint from the DDL for the table.
       #
       #   drop_constraint(:unique_name) # DROP CONSTRAINT unique_name
-      def drop_constraint(name)
-        @operations << {:op => :drop_constraint, :name => name}
+      #   drop_constraint(:unique_name, :cascade=>true) # DROP CONSTRAINT unique_name CASCADE
+      def drop_constraint(name, opts={})
+        @operations << {:op => :drop_constraint, :name => name}.merge(opts)
       end
       
       # Remove an index from the DDL for the table.