activerecord 3.2.19 → 5.0.0

data/lib/active_record/enum.rb

@@ -0,0 +1,234 @@
+require 'active_support/core_ext/object/deep_dup'
+
+module ActiveRecord
+  # Declare an enum attribute where the values map to integers in the database,
+  # but can be queried by name. Example:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum status: [ :active, :archived ]
+  #   end
+  #
+  #   # conversation.update! status: 0
+  #   conversation.active!
+  #   conversation.active? # => true
+  #   conversation.status  # => "active"
+  #
+  #   # conversation.update! status: 1
+  #   conversation.archived!
+  #   conversation.archived? # => true
+  #   conversation.status    # => "archived"
+  #
+  #   # conversation.status = 1
+  #   conversation.status = "archived"
+  #
+  #   conversation.status = nil
+  #   conversation.status.nil? # => true
+  #   conversation.status      # => nil
+  #
+  # Scopes based on the allowed values of the enum field will be provided
+  # as well. With the above example:
+  #
+  #   Conversation.active
+  #   Conversation.archived
+  #
+  # Of course, you can also query them directly if the scopes don't fit your
+  # needs:
+  #
+  #   Conversation.where(status: [:active, :archived])
+  #   Conversation.where.not(status: :active)
+  #
+  # You can set the default value from the database declaration, like:
+  #
+  #   create_table :conversations do |t|
+  #     t.column :status, :integer, default: 0
+  #   end
+  #
+  # Good practice is to let the first declared status be the default.
+  #
+  # Finally, it's also possible to explicitly map the relation between attribute and
+  # database integer with a hash:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum status: { active: 0, archived: 1 }
+  #   end
+  #
+  # Note that when an array is used, the implicit mapping from the values to database
+  # integers is derived from the order the values appear in the array. In the example,
+  # <tt>:active</tt> is mapped to +0+ as it's the first element, and <tt>:archived</tt>
+  # is mapped to +1+. In general, the +i+-th element is mapped to <tt>i-1</tt> in the
+  # database.
+  #
+  # Therefore, once a value is added to the enum array, its position in the array must
+  # be maintained, and new values should only be added to the end of the array. To
+  # remove unused values, the explicit hash syntax should be used.
+  #
+  # In rare circumstances you might need to access the mapping directly.
+  # The mappings are exposed through a class method with the pluralized attribute
+  # name, which return the mapping in a +HashWithIndifferentAccess+:
+  #
+  #   Conversation.statuses[:active]    # => 0
+  #   Conversation.statuses["archived"] # => 1
+  #
+  # Use that class method when you need to know the ordinal value of an enum.
+  # For example, you can use that when manually building SQL strings:
+  #
+  #   Conversation.where("status <> ?", Conversation.statuses[:archived])
+  #
+  # You can use the +:_prefix+ or +:_suffix+ options when you need to define
+  # multiple enums with same values. If the passed value is +true+, the methods
+  # are prefixed/suffixed with the name of the enum. It is also possible to
+  # supply a custom value:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum status: [:active, :archived], _suffix: true
+  #     enum comments_status: [:active, :inactive], _prefix: :comments
+  #   end
+  #
+  # With the above example, the bang and predicate methods along with the
+  # associated scopes are now prefixed and/or suffixed accordingly:
+  #
+  #   conversation.active_status!
+  #   conversation.archived_status? # => false
+  #
+  #   conversation.comments_inactive!
+  #   conversation.comments_active? # => false
+
+  module Enum
+    def self.extended(base) # :nodoc:
+      base.class_attribute(:defined_enums, instance_writer: false)
+      base.defined_enums = {}
+    end
+
+    def inherited(base) # :nodoc:
+      base.defined_enums = defined_enums.deep_dup
+      super
+    end
+
+    class EnumType < Type::Value # :nodoc:
+      def initialize(name, mapping, subtype)
+        @name = name
+        @mapping = mapping
+        @subtype = subtype
+      end
+
+      def cast(value)
+        return if value.blank?
+
+        if mapping.has_key?(value)
+          value.to_s
+        elsif mapping.has_value?(value)
+          mapping.key(value)
+        else
+          assert_valid_value(value)
+        end
+      end
+
+      def deserialize(value)
+        return if value.nil?
+        mapping.key(subtype.deserialize(value))
+      end
+
+      def serialize(value)
+        mapping.fetch(value, value)
+      end
+
+      def assert_valid_value(value)
+        unless value.blank? || mapping.has_key?(value) || mapping.has_value?(value)
+          raise ArgumentError, "'#{value}' is not a valid #{name}"
+        end
+      end
+
+      protected
+
+      attr_reader :name, :mapping, :subtype
+    end
+
+    def enum(definitions)
+      klass = self
+      enum_prefix = definitions.delete(:_prefix)
+      enum_suffix = definitions.delete(:_suffix)
+      definitions.each do |name, values|
+        # statuses = { }
+        enum_values = ActiveSupport::HashWithIndifferentAccess.new
+        name        = name.to_sym
+
+        # def self.statuses() statuses end
+        detect_enum_conflict!(name, name.to_s.pluralize, true)
+        klass.singleton_class.send(:define_method, name.to_s.pluralize) { enum_values }
+
+        detect_enum_conflict!(name, name)
+        detect_enum_conflict!(name, "#{name}=")
+
+        decorate_attribute_type(name, :enum) do |subtype|
+          EnumType.new(name, enum_values, subtype)
+        end
+
+        _enum_methods_module.module_eval do
+          pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index
+          pairs.each do |value, i|
+            if enum_prefix == true
+              prefix = "#{name}_"
+            elsif enum_prefix
+              prefix = "#{enum_prefix}_"
+            end
+            if enum_suffix == true
+              suffix = "_#{name}"
+            elsif enum_suffix
+              suffix = "_#{enum_suffix}"
+            end
+
+            value_method_name = "#{prefix}#{value}#{suffix}"
+            enum_values[value] = i
+
+            # def active?() status == 0 end
+            klass.send(:detect_enum_conflict!, name, "#{value_method_name}?")
+            define_method("#{value_method_name}?") { self[name] == value.to_s }
+
+            # def active!() update! status: :active end
+            klass.send(:detect_enum_conflict!, name, "#{value_method_name}!")
+            define_method("#{value_method_name}!") { update! name => value }
+
+            # scope :active, -> { where status: 0 }
+            klass.send(:detect_enum_conflict!, name, value_method_name, true)
+            klass.scope value_method_name, -> { where(name => value) }
+          end
+        end
+        defined_enums[name.to_s] = enum_values
+      end
+    end
+
+    private
+      def _enum_methods_module
+        @_enum_methods_module ||= begin
+          mod = Module.new
+          include mod
+          mod
+        end
+      end
+
+      ENUM_CONFLICT_MESSAGE = \
+        "You tried to define an enum named \"%{enum}\" on the model \"%{klass}\", but " \
+        "this will generate a %{type} method \"%{method}\", which is already defined " \
+        "by %{source}."
+
+      def detect_enum_conflict!(enum_name, method_name, klass_method = false)
+        if klass_method && dangerous_class_method?(method_name)
+          raise_conflict_error(enum_name, method_name, type: 'class')
+        elsif !klass_method && dangerous_attribute_method?(method_name)
+          raise_conflict_error(enum_name, method_name)
+        elsif !klass_method && method_defined_within?(method_name, _enum_methods_module, Module)
+          raise_conflict_error(enum_name, method_name, source: 'another enum')
+        end
+      end
+
+      def raise_conflict_error(enum_name, method_name, type: 'instance', source: 'Active Record')
+        raise ArgumentError, ENUM_CONFLICT_MESSAGE % {
+          enum: enum_name,
+          klass: self.name,
+          type: type,
+          method: method_name,
+          source: source
+        }
+      end
+  end
+end

data/lib/active_record/errors.rb

@@ -7,8 +7,10 @@ module ActiveRecord
   end
 
   # Raised when the single-table inheritance mechanism fails to locate the subclass
-  # (for example due to improper usage of column that +inheritance_column+ points to).
-  class SubclassNotFound < ActiveRecordError #:nodoc:
+  # (for example due to improper usage of column that
+  # {ActiveRecord::Base.inheritance_column}[rdoc-ref:ModelSchema::ClassMethods#inheritance_column]
+  # points to).
+  class SubclassNotFound < ActiveRecordError
   end
 
   # Raised when an object assigned to an association has an incorrect type.
@@ -22,7 +24,7 @@ module ActiveRecord
   #   end
   #
   #   # Comments are not patches, this assignment raises AssociationTypeMismatch.
-  #   @ticket.patches << Comment.new(:content => "Please attach tests to your patch.")
+  #   @ticket.patches << Comment.new(content: "Please attach tests to your patch.")
   class AssociationTypeMismatch < ActiveRecordError
   end
 
@@ -30,49 +32,91 @@ module ActiveRecord
   class SerializationTypeMismatch < ActiveRecordError
   end
 
-  # Raised when adapter not specified on connection (or configuration file <tt>config/database.yml</tt>
-  # misses adapter field).
+  # Raised when adapter not specified on connection (or configuration file
+  # +config/database.yml+ misses adapter field).
   class AdapterNotSpecified < ActiveRecordError
   end
 
-  # Raised when Active Record cannot find database adapter specified in <tt>config/database.yml</tt> or programmatically.
+  # Raised when Active Record cannot find database adapter specified in
+  # +config/database.yml+ or programmatically.
   class AdapterNotFound < ActiveRecordError
   end
 
-  # Raised when connection to the database could not been established (for example when <tt>connection=</tt>
+  # Raised when connection to the database could not been established (for example when
+  # {ActiveRecord::Base.connection=}[rdoc-ref:ConnectionHandling#connection]
   # is given a nil object).
   class ConnectionNotEstablished < ActiveRecordError
   end
 
-  # Raised when Active Record cannot find record by given id or set of ids.
+  # Raised when Active Record cannot find a record by given id or set of ids.
   class RecordNotFound < ActiveRecordError
+    attr_reader :model, :primary_key, :id
+
+    def initialize(message = nil, model = nil, primary_key = nil, id = nil)
+      @primary_key = primary_key
+      @model = model
+      @id = id
+
+      super(message)
+    end
   end
 
-  # Raised by ActiveRecord::Base.save! and ActiveRecord::Base.create! methods when record cannot be
-  # saved because record is invalid.
+  # Raised by {ActiveRecord::Base#save!}[rdoc-ref:Persistence#save!] and
+  # {ActiveRecord::Base.create!}[rdoc-ref:Persistence::ClassMethods#create!]
+  # methods when a record is invalid and can not be saved.
   class RecordNotSaved < ActiveRecordError
-  end
+    attr_reader :record
 
-  # Raised when SQL statement cannot be executed by the database (for example, it's often the case for
-  # MySQL when Ruby driver used is too old).
-  class StatementInvalid < ActiveRecordError
+    def initialize(message = nil, record = nil)
+      @record = record
+      super(message)
+    end
   end
 
-  # Raised when SQL statement is invalid and the application gets a blank result.
-  class ThrowResult < ActiveRecordError
+  # Raised by {ActiveRecord::Base#destroy!}[rdoc-ref:Persistence#destroy!]
+  # when a call to {#destroy}[rdoc-ref:Persistence#destroy!]
+  # would return false.
+  #
+  #   begin
+  #     complex_operation_that_internally_calls_destroy!
+  #   rescue ActiveRecord::RecordNotDestroyed => invalid
+  #     puts invalid.record.errors
+  #   end
+  #
+  class RecordNotDestroyed < ActiveRecordError
+    attr_reader :record
+
+    def initialize(message = nil, record = nil)
+      @record = record
+      super(message)
+    end
   end
 
-  # Parent class for all specific exceptions which wrap database driver exceptions
-  # provides access to the original exception also.
-  class WrappedDatabaseException < StatementInvalid
-    attr_reader :original_exception
+  # Superclass for all database execution errors.
+  #
+  # Wraps the underlying database error as +cause+.
+  class StatementInvalid < ActiveRecordError
 
-    def initialize(message, original_exception)
-      super(message)
-      @original_exception = original_exception
+    def initialize(message = nil, original_exception = nil)
+      if original_exception
+        ActiveSupport::Deprecation.warn("Passing #original_exception is deprecated and has no effect. " \
+                                        "Exceptions will automatically capture the original exception.", caller)
+      end
+
+      super(message || $!.try(:message))
+    end
+
+    def original_exception
+      ActiveSupport::Deprecation.warn("#original_exception is deprecated. Use #cause instead.", caller)
+      cause
     end
   end
 
+  # Defunct wrapper class kept for compatibility.
+  # StatementInvalid wraps the original exception now.
+  class WrappedDatabaseException < StatementInvalid
+  end
+
   # Raised when a record cannot be inserted because it would violate a uniqueness constraint.
   class RecordNotUnique < WrappedDatabaseException
   end
@@ -81,38 +125,55 @@ module ActiveRecord
   class InvalidForeignKey < WrappedDatabaseException
   end
 
-  # Raised when number of bind variables in statement given to <tt>:condition</tt> key (for example,
-  # when using +find+ method)
-  # does not match number of expected variables.
+  # Raised when a record cannot be inserted or updated because a value too long for a column type.
+  class ValueTooLong < StatementInvalid
+  end
+
+  # Raised when number of bind variables in statement given to +:condition+ key
+  # (for example, when using {ActiveRecord::Base.find}[rdoc-ref:FinderMethods#find] method)
+  # does not match number of expected values supplied.
   #
-  # For example, in
+  # For example, when there are two placeholders with only one value supplied:
   #
   #   Location.where("lat = ? AND lng = ?", 53.7362)
-  #
-  # two placeholders are given but only one variable to fill them.
   class PreparedStatementInvalid < ActiveRecordError
   end
 
+  # Raised when a given database does not exist.
+  class NoDatabaseError < StatementInvalid
+  end
+
+  # Raised when Postgres returns 'cached plan must not change result type' and
+  # we cannot retry gracefully (e.g. inside a transaction)
+  class PreparedStatementCacheExpired < StatementInvalid
+  end
+
   # Raised on attempt to save stale record. Record is stale when it's being saved in another query after
   # instantiation, for example, when two users edit the same wiki page and one starts editing and saves
   # the page before the other.
   #
-  # Read more about optimistic locking in ActiveRecord::Locking module RDoc.
+  # Read more about optimistic locking in ActiveRecord::Locking module
+  # documentation.
   class StaleObjectError < ActiveRecordError
     attr_reader :record, :attempted_action
 
-    def initialize(record, attempted_action)
-      @record = record
-      @attempted_action = attempted_action
+    def initialize(record = nil, attempted_action = nil)
+      if record && attempted_action
+        @record = record
+        @attempted_action = attempted_action
+        super("Attempted to #{attempted_action} a stale object: #{record.class.name}.")
+      else
+        super("Stale object error.")
+      end
     end
 
-    def message
-      "Attempted to #{attempted_action} a stale object: #{record.class.name}"
-    end
   end
 
-  # Raised when association is being configured improperly or
-  # user tries to use offset and limit together with has_many or has_and_belongs_to_many associations.
+  # Raised when association is being configured improperly or user tries to use
+  # offset and limit together with
+  # {ActiveRecord::Base.has_many}[rdoc-ref:Associations::ClassMethods#has_many] or
+  # {ActiveRecord::Base.has_and_belongs_to_many}[rdoc-ref:Associations::ClassMethods#has_and_belongs_to_many]
+  # associations.
   class ConfigurationError < ActiveRecordError
   end
 
@@ -120,9 +181,10 @@ module ActiveRecord
   class ReadOnlyRecord < ActiveRecordError
   end
 
-  # ActiveRecord::Transactions::ClassMethods.transaction uses this exception
-  # to distinguish a deliberate rollback from other exceptional situations.
-  # Normally, raising an exception will cause the +transaction+ method to rollback
+  # {ActiveRecord::Base.transaction}[rdoc-ref:Transactions::ClassMethods#transaction]
+  # uses this exception to distinguish a deliberate rollback from other exceptional situations.
+  # Normally, raising an exception will cause the
+  # {.transaction}[rdoc-ref:Transactions::ClassMethods#transaction] method to rollback
   # the database transaction *and* pass on the exception. But if you raise an
   # ActiveRecord::Rollback exception, then the database transaction will be rolled back,
   # without passing on the exception.
@@ -150,46 +212,81 @@ module ActiveRecord
   class Rollback < ActiveRecordError
   end
 
-  # Raised when attribute has a name reserved by Active Record (when attribute has name of one of Active Record instance methods).
+  # Raised when attribute has a name reserved by Active Record (when attribute
+  # has name of one of Active Record instance methods).
   class DangerousAttributeError < ActiveRecordError
   end
 
   # Raised when unknown attributes are supplied via mass assignment.
-  class UnknownAttributeError < NoMethodError
-  end
+  UnknownAttributeError = ActiveModel::UnknownAttributeError
 
   # Raised when an error occurred while doing a mass assignment to an attribute through the
-  # <tt>attributes=</tt> method. The exception has an +attribute+ property that is the name of the
-  # offending attribute.
+  # {ActiveRecord::Base#attributes=}[rdoc-ref:AttributeAssignment#attributes=] method.
+  # The exception has an +attribute+ property that is the name of the offending attribute.
   class AttributeAssignmentError < ActiveRecordError
     attr_reader :exception, :attribute
-    def initialize(message, exception, attribute)
+
+    def initialize(message = nil, exception = nil, attribute = nil)
+      super(message)
       @exception = exception
       @attribute = attribute
-      @message = message
     end
   end
 
-  # Raised when there are multiple errors while doing a mass assignment through the +attributes+
+  # Raised when there are multiple errors while doing a mass assignment through the
+  # {ActiveRecord::Base#attributes=}[rdoc-ref:AttributeAssignment#attributes=]
   # method. The exception has an +errors+ property that contains an array of AttributeAssignmentError
   # objects, each corresponding to the error while assigning to an attribute.
   class MultiparameterAssignmentErrors < ActiveRecordError
     attr_reader :errors
-    def initialize(errors)
+
+    def initialize(errors = nil)
       @errors = errors
     end
   end
 
-  # Raised when a primary key is needed, but there is not one specified in the schema or model.
+  # Raised when a primary key is needed, but not specified in the schema or model.
   class UnknownPrimaryKey < ActiveRecordError
     attr_reader :model
 
-    def initialize(model)
-      @model = model
+    def initialize(model = nil, description = nil)
+      if model
+        message = "Unknown primary key for table #{model.table_name} in model #{model}."
+        message += "\n#{description}" if description
+        @model = model
+        super(message)
+      else
+        super("Unknown primary key.")
+      end
     end
+  end
 
-    def message
-      "Unknown primary key for table #{model.table_name} in model #{model}."
-    end
+  # Raised when a relation cannot be mutated because it's already loaded.
+  #
+  #   class Task < ActiveRecord::Base
+  #   end
+  #
+  #   relation = Task.all
+  #   relation.loaded? # => true
+  #
+  #   # Methods which try to mutate a loaded relation fail.
+  #   relation.where!(title: 'TODO')  # => ActiveRecord::ImmutableRelation
+  #   relation.limit!(5)              # => ActiveRecord::ImmutableRelation
+  class ImmutableRelation < ActiveRecordError
+  end
+
+  # TransactionIsolationError will be raised under the following conditions:
+  #
+  # * The adapter does not support setting the isolation level
+  # * You are joining an existing open transaction
+  # * You are creating a nested (savepoint) transaction
+  #
+  # The mysql2 and postgresql adapters support setting the transaction isolation level.
+  class TransactionIsolationError < ActiveRecordError
+  end
+
+  # IrreversibleOrderError is raised when a relation's order is too complex for
+  # +reverse_order+ to automatically reverse.
+  class IrreversibleOrderError < ActiveRecordError
   end
 end

data/lib/active_record/explain.rb

@@ -1,62 +1,22 @@
-require 'active_support/core_ext/class/attribute'
+require 'active_support/lazy_load_hooks'
+require 'active_record/explain_registry'
 
 module ActiveRecord
   module Explain
-    def self.extended(base)
-      base.class_eval do
-        # If a query takes longer than these many seconds we log its query plan
-        # automatically. nil disables this feature.
-        class_attribute :auto_explain_threshold_in_seconds, :instance_writer => false
-        self.auto_explain_threshold_in_seconds = nil
-      end
-    end
-
-    # If the database adapter supports explain and auto explain is enabled,
-    # this method triggers EXPLAIN logging for the queries triggered by the
-    # block if it takes more than the threshold as a whole. That is, the
-    # threshold is not checked against each individual query, but against the
-    # duration of the entire block. This approach is convenient for relations.
-
-    #
-    # The available_queries_for_explain thread variable collects the queries
-    # to be explained. If the value is nil, it means queries are not being
-    # currently collected. A false value indicates collecting is turned
-    # off. Otherwise it is an array of queries.
-    def logging_query_plan # :nodoc:
-      return yield unless logger
-
-      threshold = auto_explain_threshold_in_seconds
-      current   = Thread.current
-      if connection.supports_explain? && threshold && current[:available_queries_for_explain].nil?
-        begin
-          queries = current[:available_queries_for_explain] = []
-          start = Time.now
-          result = yield
-          logger.warn(exec_explain(queries)) if Time.now - start > threshold
-          result
-        ensure
-          current[:available_queries_for_explain] = nil
-        end
-      else
-        yield
-      end
-    end
-
-    # Relation#explain needs to be able to collect the queries regardless of
-    # whether auto explain is enabled. This method serves that purpose.
+    # Executes the block with the collect flag enabled. Queries are collected
+    # asynchronously by the subscriber and returned.
     def collecting_queries_for_explain # :nodoc:
-      current = Thread.current
-      original, current[:available_queries_for_explain] = current[:available_queries_for_explain], []
-      return yield, current[:available_queries_for_explain]
+      ExplainRegistry.collect = true
+      yield
+      ExplainRegistry.queries
     ensure
-      # Note that the return value above does not depend on this assigment.
-      current[:available_queries_for_explain] = original
+      ExplainRegistry.reset
     end
 
     # Makes the adapter execute EXPLAIN for the tuples of queries and bindings.
     # Returns a formatted string ready to be logged.
     def exec_explain(queries) # :nodoc:
-      queries && queries.map do |sql, bind|
+      str = queries.map do |sql, bind|
         [].tap do |msg|
           msg << "EXPLAIN for: #{sql}"
           unless bind.empty?
@@ -66,21 +26,13 @@ module ActiveRecord
           msg << connection.explain(sql, bind)
         end.join("\n")
       end.join("\n")
-    end
 
-    # Silences automatic EXPLAIN logging for the duration of the block.
-    #
-    # This has high priority, no EXPLAINs will be run even if downwards
-    # the threshold is set to 0.
-    #
-    # As the name of the method suggests this only applies to automatic
-    # EXPLAINs, manual calls to +ActiveRecord::Relation#explain+ run.
-    def silence_auto_explain
-      current = Thread.current
-      original, current[:available_queries_for_explain] = current[:available_queries_for_explain], false
-      yield
-    ensure
-      current[:available_queries_for_explain] = original
+      # Overriding inspect to be more human readable, especially in the console.
+      def str.inspect
+        self
+      end
+
+      str
     end
   end
 end

data/lib/active_record/explain_registry.rb

@@ -0,0 +1,30 @@
+require 'active_support/per_thread_registry'
+
+module ActiveRecord
+  # This is a thread locals registry for EXPLAIN. For example
+  #
+  #   ActiveRecord::ExplainRegistry.queries
+  #
+  # returns the collected queries local to the current thread.
+  #
+  # See the documentation of ActiveSupport::PerThreadRegistry
+  # for further details.
+  class ExplainRegistry # :nodoc:
+    extend ActiveSupport::PerThreadRegistry
+
+    attr_accessor :queries, :collect
+
+    def initialize
+      reset
+    end
+
+    def collect?
+      @collect
+    end
+
+    def reset
+      @collect = false
+      @queries = []
+    end
+  end
+end