activerecord 5.2.8 → 7.0.2

data/lib/active_record/enum.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/hash/slice"
 require "active_support/core_ext/object/deep_dup"
 
 module ActiveRecord
@@ -7,7 +8,7 @@ module ActiveRecord
   # but can be queried by name. Example:
   #
   #   class Conversation < ActiveRecord::Base
-  #     enum status: [ :active, :archived ]
+  #     enum :status, [ :active, :archived ]
   #   end
   #
   #   # conversation.update! status: 0
@@ -31,7 +32,9 @@ module ActiveRecord
   # as well. With the above example:
   #
   #   Conversation.active
+  #   Conversation.not_active
   #   Conversation.archived
+  #   Conversation.not_archived
   #
   # Of course, you can also query them directly if the scopes don't fit your
   # needs:
@@ -39,19 +42,33 @@ module ActiveRecord
   #   Conversation.where(status: [:active, :archived])
   #   Conversation.where.not(status: :active)
   #
-  # You can set the default value from the database declaration, like:
+  # Defining scopes can be disabled by setting +:scopes+ to +false+.
   #
-  #   create_table :conversations do |t|
-  #     t.column :status, :integer, default: 0
+  #   class Conversation < ActiveRecord::Base
+  #     enum :status, [ :active, :archived ], scopes: false
   #   end
   #
-  # Good practice is to let the first declared status be the default.
+  # You can set the default enum value by setting +:default+, like:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum :status, [ :active, :archived ], default: :active
+  #   end
   #
-  # Finally, it's also possible to explicitly map the relation between attribute and
+  #   conversation = Conversation.new
+  #   conversation.status # => "active"
+  #
+  # It's possible to explicitly map the relation between attribute and
   # database integer with a hash:
   #
   #   class Conversation < ActiveRecord::Base
-  #     enum status: { active: 0, archived: 1 }
+  #     enum :status, active: 0, archived: 1
+  #   end
+  #
+  # Finally it's also possible to use a string column to persist the enumerated value.
+  # Note that this will likely lead to slower database queries:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum :status, active: "active", archived: "archived"
   #   end
   #
   # Note that when an array is used, the implicit mapping from the values to database
@@ -76,14 +93,14 @@ module ActiveRecord
   #
   #   Conversation.where("status <> ?", Conversation.statuses[:archived])
   #
-  # You can use the +:_prefix+ or +:_suffix+ options when you need to define
+  # 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
+  #     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
@@ -94,7 +111,6 @@ module ActiveRecord
   #
   #   conversation.comments_inactive!
   #   conversation.comments_active? # => false
-
   module Enum
     def self.extended(base) # :nodoc:
       base.class_attribute(:defined_enums, instance_writer: false, default: {})
@@ -115,24 +131,25 @@ module ActiveRecord
       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)
+          value.presence
         end
       end
 
       def deserialize(value)
-        return if value.nil?
         mapping.key(subtype.deserialize(value))
       end
 
       def serialize(value)
-        mapping.fetch(value, value)
+        subtype.serialize(mapping.fetch(value, value))
+      end
+
+      def serializable?(value, &block)
+        subtype.serializable?(mapping.fetch(value, value), &block)
       end
 
       def assert_valid_value(value)
@@ -141,83 +158,132 @@ module ActiveRecord
         end
       end
 
-      # TODO Change this to private once we've dropped Ruby 2.2 support.
-      # Workaround for Ruby 2.2 "private attribute?" warning.
-      protected
+      attr_reader :subtype
+
+      private
+        attr_reader :name, :mapping
+    end
+
+    def enum(name = nil, values = nil, **options)
+      if name
+        values, options = options, {} unless values
+        return _enum(name, values, **options)
+      end
+
+      definitions = options.slice!(:_prefix, :_suffix, :_scopes, :_default)
+      options.transform_keys! { |key| :"#{key[1..-1]}" }
 
-        attr_reader :name, :mapping, :subtype
+      definitions.each { |name, values| _enum(name, values, **options) }
     end
 
-    def enum(definitions)
-      klass = self
-      enum_prefix = definitions.delete(:_prefix)
-      enum_suffix = definitions.delete(:_suffix)
-      definitions.each do |name, values|
+    private
+      def _enum(name, values, prefix: nil, suffix: nil, scopes: true, **options)
+        assert_valid_enum_definition_values(values)
         # statuses = { }
         enum_values = ActiveSupport::HashWithIndifferentAccess.new
         name = name.to_s
 
         # def self.statuses() statuses end
         detect_enum_conflict!(name, name.pluralize, true)
-        singleton_class.send(:define_method, name.pluralize) { enum_values }
+        singleton_class.define_method(name.pluralize) { enum_values }
         defined_enums[name] = enum_values
 
         detect_enum_conflict!(name, name)
         detect_enum_conflict!(name, "#{name}=")
 
-        attr = attribute_alias?(name) ? attribute_alias(name) : name
-        decorate_attribute_type(attr, :enum) do |subtype|
-          EnumType.new(attr, enum_values, subtype)
+        attribute(name, **options) do |subtype|
+          subtype = subtype.subtype if EnumType === subtype
+          EnumType.new(name, enum_values, subtype)
         end
 
+        value_method_names = []
         _enum_methods_module.module_eval do
+          prefix = if prefix
+            prefix == true ? "#{name}_" : "#{prefix}_"
+          end
+
+          suffix = if suffix
+            suffix == true ? "_#{name}" : "_#{suffix}"
+          end
+
           pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index
           pairs.each do |label, value|
-            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}#{label}#{suffix}"
             enum_values[label] = value
             label = label.to_s
 
-            # def active?() status == "active" end
+            value_method_name = "#{prefix}#{label}#{suffix}"
+            value_method_names << value_method_name
+            define_enum_methods(name, value_method_name, value, scopes)
+
+            method_friendly_label = label.gsub(/[\W&&[:ascii:]]+/, "_")
+            value_method_alias = "#{prefix}#{method_friendly_label}#{suffix}"
+
+            if value_method_alias != value_method_name && !value_method_names.include?(value_method_alias)
+              value_method_names << value_method_alias
+              define_enum_methods(name, value_method_alias, value, scopes)
+            end
+          end
+        end
+        detect_negative_enum_conditions!(value_method_names) if scopes
+        enum_values.freeze
+      end
+
+      class EnumMethods < Module # :nodoc:
+        def initialize(klass)
+          @klass = klass
+        end
+
+        private
+          attr_reader :klass
+
+          def define_enum_methods(name, value_method_name, value, scopes)
+            # def active?() status_for_database == 0 end
             klass.send(:detect_enum_conflict!, name, "#{value_method_name}?")
-            define_method("#{value_method_name}?") { self[attr] == label }
+            define_method("#{value_method_name}?") { public_send(:"#{name}_for_database") == value }
 
             # def active!() update!(status: 0) end
             klass.send(:detect_enum_conflict!, name, "#{value_method_name}!")
-            define_method("#{value_method_name}!") { update!(attr => value) }
+            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(attr => value) }
+            # scope :not_active, -> { where.not(status: 0) }
+            if scopes
+              klass.send(:detect_enum_conflict!, name, value_method_name, true)
+              klass.scope value_method_name, -> { where(name => value) }
+
+              klass.send(:detect_enum_conflict!, name, "not_#{value_method_name}", true)
+              klass.scope "not_#{value_method_name}", -> { where.not(name => value) }
+            end
           end
-        end
-        enum_values.freeze
       end
-    end
+      private_constant :EnumMethods
 
-    private
       def _enum_methods_module
         @_enum_methods_module ||= begin
-          mod = Module.new
+          mod = EnumMethods.new(self)
           include mod
           mod
         end
       end
 
+      def assert_valid_enum_definition_values(values)
+        unless values.is_a?(Hash) || values.all?(Symbol) || values.all?(String)
+          error_message = <<~MSG
+            Enum values #{values} must be either a hash, an array of symbols, or an array of strings.
+          MSG
+          raise ArgumentError, error_message
+        end
+
+        if values.is_a?(Hash) && values.keys.any?(&:blank?) || values.is_a?(Array) && values.any?(&:blank?)
+          raise ArgumentError, "Enum label name must not be blank."
+        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}."
+      private_constant :ENUM_CONFLICT_MESSAGE
 
       def detect_enum_conflict!(enum_name, method_name, klass_method = false)
         if klass_method && dangerous_class_method?(method_name)
@@ -240,5 +306,18 @@ module ActiveRecord
           source: source
         }
       end
+
+      def detect_negative_enum_conditions!(method_names)
+        return unless logger
+
+        method_names.select { |m| m.start_with?("not_") }.each do |potential_not|
+          inverted_form = potential_not.sub("not_", "")
+          if method_names.include?(inverted_form)
+            logger.warn "Enum element '#{potential_not}' in #{self.name} uses the prefix 'not_'." \
+              " This has caused a conflict with auto generated negative scopes." \
+              " Avoid using enum elements starting with 'not' where the positive form is also an element."
+          end
+        end
+      end
   end
 end

data/lib/active_record/errors.rb

@@ -7,6 +7,10 @@ module ActiveRecord
   class ActiveRecordError < StandardError
   end
 
+  # Raised when trying to use a feature in Active Record which requires Active Job but the gem is not present.
+  class ActiveJobRequiredError < ActiveRecordError
+  end
+
   # Raised when the single-table inheritance mechanism fails to locate the subclass
   # (for example due to improper usage of column that
   # {ActiveRecord::Base.inheritance_column}[rdoc-ref:ModelSchema::ClassMethods#inheritance_column]
@@ -38,6 +42,10 @@ module ActiveRecord
   class AdapterNotSpecified < ActiveRecordError
   end
 
+  # Raised when a model makes a query but it has not specified an associated table.
+  class TableNotSpecified < ActiveRecordError
+  end
+
   # Raised when Active Record cannot find database adapter specified in
   # +config/database.yml+ or programmatically.
   class AdapterNotFound < ActiveRecordError
@@ -49,6 +57,47 @@ module ActiveRecord
   class ConnectionNotEstablished < ActiveRecordError
   end
 
+  # Raised when a connection could not be obtained within the connection
+  # acquisition timeout period: because max connections in pool
+  # are in use.
+  class ConnectionTimeoutError < ConnectionNotEstablished
+  end
+
+  # Raised when connection to the database could not been established because it was not
+  # able to connect to the host or when the authorization failed.
+  class DatabaseConnectionError < ConnectionNotEstablished
+    def initialize(message = nil)
+      super(message || "Database connection error")
+    end
+
+    class << self
+      def hostname_error(hostname)
+        DatabaseConnectionError.new(<<~MSG)
+          There is an issue connecting with your hostname: #{hostname}.\n
+          Please check your database configuration and ensure there is a valid connection to your database.
+        MSG
+      end
+
+      def username_error(username)
+        DatabaseConnectionError.new(<<~MSG)
+          There is an issue connecting to your database with your username/password, username: #{username}.\n
+          Please check your database configuration to ensure the username/password are valid.
+        MSG
+      end
+    end
+  end
+
+  # Raised when a pool was unable to get ahold of all its connections
+  # to perform a "group" action such as
+  # {ActiveRecord::Base.connection_pool.disconnect!}[rdoc-ref:ConnectionAdapters::ConnectionPool#disconnect!]
+  # or {ActiveRecord::Base.clear_reloadable_connections!}[rdoc-ref:ConnectionAdapters::ConnectionHandler#clear_reloadable_connections!].
+  class ExclusiveConnectionTimeoutError < ConnectionTimeoutError
+  end
+
+  # Raised when a write to the database is attempted on a read only connection.
+  class ReadOnlyError < ActiveRecordError
+  end
+
   # Raised when Active Record cannot find a record by given id or set of ids.
   class RecordNotFound < ActiveRecordError
     attr_reader :model, :primary_key, :id
@@ -64,7 +113,7 @@ module ActiveRecord
 
   # 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.
+  # methods when a record is invalid and cannot be saved.
   class RecordNotSaved < ActiveRecordError
     attr_reader :record
 
@@ -75,7 +124,7 @@ module ActiveRecord
   end
 
   # Raised by {ActiveRecord::Base#destroy!}[rdoc-ref:Persistence#destroy!]
-  # when a call to {#destroy}[rdoc-ref:Persistence#destroy!]
+  # when a call to {#destroy}[rdoc-ref:Persistence#destroy]
   # would return false.
   #
   #   begin
@@ -93,13 +142,27 @@ module ActiveRecord
     end
   end
 
+  # Raised when Active Record finds multiple records but only expected one.
+  class SoleRecordExceeded < ActiveRecordError
+    attr_reader :record
+
+    def initialize(record = nil)
+      @record = record
+      super "Wanted only one #{record&.name || "record"}"
+    end
+  end
+
   # Superclass for all database execution errors.
   #
   # Wraps the underlying database error as +cause+.
   class StatementInvalid < ActiveRecordError
-    def initialize(message = nil)
-      super(message || $!.try(:message))
+    def initialize(message = nil, sql: nil, binds: nil)
+      super(message || $!&.message)
+      @sql = sql
+      @binds = binds
     end
+
+    attr_reader :sql, :binds
   end
 
   # Defunct wrapper class kept for compatibility.
@@ -111,14 +174,14 @@ module ActiveRecord
   class RecordNotUnique < WrappedDatabaseException
   end
 
-  # Raised when a record cannot be inserted or updated because it references a non-existent record.
+  # Raised when a record cannot be inserted or updated because it references a non-existent record,
+  # or when a record cannot be deleted because a parent record references it.
   class InvalidForeignKey < WrappedDatabaseException
   end
 
   # Raised when a foreign key constraint cannot be added because the column type does not match the referenced column type.
   class MismatchedForeignKey < StatementInvalid
     def initialize(
-      adapter = nil,
       message: nil,
       sql: nil,
       binds: nil,
@@ -130,14 +193,14 @@ module ActiveRecord
     )
       if table
         type = primary_key_column.bigint? ? :bigint : primary_key_column.type
-        msg = <<-EOM.squish
+        msg = <<~EOM.squish
           Column `#{foreign_key}` on table `#{table}` does not match column `#{primary_key}` on `#{target_table}`,
           which has type `#{primary_key_column.sql_type}`.
           To resolve this issue, change the type of the `#{foreign_key}` column on `#{table}` to be :#{type}.
           (For example `t.#{type} :#{foreign_key}`).
         EOM
       else
-        msg = <<-EOM.squish
+        msg = <<~EOM.squish
           There is a mismatch between the foreign key and primary key column types.
           Verify that the foreign key column type and the primary key of the associated table match types.
         EOM
@@ -145,7 +208,7 @@ module ActiveRecord
       if message
         msg << "\nOriginal message: #{message}"
       end
-      super(msg)
+      super(msg, sql: sql, binds: binds)
     end
   end
 
@@ -161,9 +224,9 @@ module ActiveRecord
   class RangeError < 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.
+  # Raised when the number of placeholders in an SQL fragment passed to
+  # {ActiveRecord::Base.where}[rdoc-ref:QueryMethods#where]
+  # does not match the number of values supplied.
   #
   # For example, when there are two placeholders with only one value supplied:
   #
@@ -173,6 +236,34 @@ module ActiveRecord
 
   # Raised when a given database does not exist.
   class NoDatabaseError < StatementInvalid
+    include ActiveSupport::ActionableError
+
+    action "Create database" do
+      ActiveRecord::Tasks::DatabaseTasks.create_current
+    end
+
+    def initialize(message = nil)
+      super(message || "Database not found")
+    end
+
+    class << self
+      def db_error(db_name)
+        NoDatabaseError.new(<<~MSG)
+          We could not find your database: #{db_name}. Which can be found in the database configuration file located at config/database.yml.
+
+          To resolve this issue:
+
+          - Did you create the database for this app, or delete it? You may need to create your database.
+          - Has the database name changed? Check your database.yml config has the correct database name.
+
+          To create your database, run:\n\n        bin/rails db:create
+        MSG
+      end
+    end
+  end
+
+  # Raised when creating a database if it exists.
+  class DatabaseAlreadyExists < StatementInvalid
   end
 
   # Raised when PostgreSQL returns 'cached plan must not change result type' and
@@ -212,6 +303,10 @@ module ActiveRecord
   class ReadOnlyRecord < ActiveRecordError
   end
 
+  # Raised on attempt to lazily load records that are marked as strict loading.
+  class StrictLoadingViolationError < ActiveRecordError
+  end
+
   # {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
@@ -231,7 +326,7 @@ module ActiveRecord
   #           # The system must fail on Friday so that our support department
   #           # won't be out of job. We silently rollback this transaction
   #           # without telling the user.
-  #           raise ActiveRecord::Rollback, "Call tech support!"
+  #           raise ActiveRecord::Rollback
   #         end
   #       end
   #       # ActiveRecord::Rollback is the only exception that won't be passed on
@@ -322,10 +417,15 @@ module ActiveRecord
   # See the following:
   #
   # * https://www.postgresql.org/docs/current/static/transaction-iso.html
-  # * https://dev.mysql.com/doc/refman/5.7/en/error-messages-server.html#error_er_lock_deadlock
+  # * https://dev.mysql.com/doc/mysql-errors/en/server-error-reference.html#error_er_lock_deadlock
   class TransactionRollbackError < StatementInvalid
   end
 
+  # AsynchronousQueryInsideTransactionError will be raised when attempting
+  # to perform an asynchronous query from inside a transaction
+  class AsynchronousQueryInsideTransactionError < ActiveRecordError
+  end
+
   # SerializationFailure will be raised when a transaction is rolled
   # back by the database due to a serialization failure.
   class SerializationFailure < TransactionRollbackError
@@ -341,37 +441,43 @@ module ActiveRecord
   class IrreversibleOrderError < ActiveRecordError
   end
 
+  # Superclass for errors that have been aborted (either by client or server).
+  class QueryAborted < StatementInvalid
+  end
+
   # LockWaitTimeout will be raised when lock wait timeout exceeded.
   class LockWaitTimeout < StatementInvalid
   end
 
   # StatementTimeout will be raised when statement timeout exceeded.
-  class StatementTimeout < StatementInvalid
+  class StatementTimeout < QueryAborted
   end
 
   # QueryCanceled will be raised when canceling statement due to user request.
-  class QueryCanceled < StatementInvalid
+  class QueryCanceled < QueryAborted
+  end
+
+  # AdapterTimeout will be raised when database clients times out while waiting from the server.
+  class AdapterTimeout < QueryAborted
   end
 
   # UnknownAttributeReference is raised when an unknown and potentially unsafe
-  # value is passed to a query method when allow_unsafe_raw_sql is set to
-  # :disabled. For example, passing a non column name value to a relation's
-  # #order method might cause this exception.
+  # value is passed to a query method. For example, passing a non column name
+  # value to a relation's #order method might cause this exception.
   #
   # When working around this exception, caution should be taken to avoid SQL
   # injection vulnerabilities when passing user-provided values to query
   # methods. Known-safe values can be passed to query methods by wrapping them
   # in Arel.sql.
   #
-  # For example, with allow_unsafe_raw_sql set to :disabled, the following
-  # code would raise this exception:
+  # For example, the following code would raise this exception:
   #
-  #   Post.order("length(title)").first
+  #   Post.order("REPLACE(title, 'misc', 'zzzz') asc").pluck(:id)
   #
   # The desired result can be accomplished by wrapping the known-safe string
   # in Arel.sql:
   #
-  #   Post.order(Arel.sql("length(title)")).first
+  #   Post.order(Arel.sql("REPLACE(title, 'misc', 'zzzz') asc")).pluck(:id)
   #
   # Again, such a workaround should *not* be used when passing user-provided
   # values, such as request parameters or model attributes to query methods.

data/lib/active_record/explain.rb

@@ -18,7 +18,7 @@ module ActiveRecord
     # Returns a formatted string ready to be logged.
     def exec_explain(queries) # :nodoc:
       str = queries.map do |sql, binds|
-        msg = "EXPLAIN for: #{sql}".dup
+        msg = +"EXPLAIN for: #{sql}"
         unless binds.empty?
           msg << " "
           msg << binds.map { |attr| render_bind(attr) }.inspect
@@ -36,15 +36,19 @@ module ActiveRecord
     end
 
     private
-
       def render_bind(attr)
-        value = if attr.type.binary? && attr.value
-          "<#{attr.value_for_database.to_s.bytesize} bytes of binary data>"
+        if ActiveModel::Attribute === attr
+          value = if attr.type.binary? && attr.value
+            "<#{attr.value_for_database.to_s.bytesize} bytes of binary data>"
+          else
+            connection.type_cast(attr.value_for_database)
+          end
         else
-          connection.type_cast(attr.value_for_database)
+          value = connection.type_cast(attr)
+          attr  = nil
         end
 
-        [attr.name, value]
+        [attr&.name, value]
       end
   end
 end

data/lib/active_record/explain_registry.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "active_support/per_thread_registry"
+require "active_support/core_ext/module/delegation"
 
 module ActiveRecord
   # This is a thread locals registry for EXPLAIN. For example
@@ -8,13 +8,18 @@ module ActiveRecord
   #   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
+    class << self
+      delegate :reset, :collect, :collect=, :collect?, :queries, to: :instance
+
+      private
+        def instance
+          ActiveSupport::IsolatedExecutionState[:active_record_explain_registry] ||= new
+        end
+    end
 
-    attr_accessor :queries, :collect
+    attr_accessor :collect
+    attr_reader :queries
 
     def initialize
       reset

data/lib/active_record/explain_subscriber.rb

@@ -26,7 +26,7 @@ module ActiveRecord
       payload[:exception] ||
         payload[:cached] ||
         IGNORED_PAYLOADS.include?(payload[:name]) ||
-        payload[:sql] !~ EXPLAINED_SQLS
+        !payload[:sql].match?(EXPLAINED_SQLS)
     end
 
     ActiveSupport::Notifications.subscribe("sql.active_record", new)