activerecord 6.0.1 → 6.1.7.2

data/lib/active_record/delegated_type.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inquiry"
+
+module ActiveRecord
+  # == Delegated types
+  #
+  # Class hierarchies can map to relational database tables in many ways. Active Record, for example, offers
+  # purely abstract classes, where the superclass doesn't persist any attributes, and single-table inheritance,
+  # where all attributes from all levels of the hierarchy are represented in a single table. Both have their
+  # places, but neither are without their drawbacks.
+  #
+  # The problem with purely abstract classes is that all concrete subclasses must persist all the shared
+  # attributes themselves in their own tables (also known as class-table inheritance). This makes it hard to
+  # do queries across the hierarchy. For example, imagine you have the following hierarchy:
+  #
+  #   Entry < ApplicationRecord
+  #   Message < Entry
+  #   Comment < Entry
+  #
+  # How do you show a feed that has both +Message+ and +Comment+ records, which can be easily paginated?
+  # Well, you can't! Messages are backed by a messages table and comments by a comments table. You can't
+  # pull from both tables at once and use a consistent OFFSET/LIMIT scheme.
+  #
+  # You can get around the pagination problem by using single-table inheritance, but now you're forced into
+  # a single mega table with all the attributes from all subclasses. No matter how divergent. If a Message
+  # has a subject, but the comment does not, well, now the comment does anyway! So STI works best when there's
+  # little divergence between the subclasses and their attributes.
+  #
+  # But there's a third way: Delegated types. With this approach, the "superclass" is a concrete class
+  # that is represented by its own table, where all the superclass attributes that are shared amongst all the
+  # "subclasses" are stored. And then each of the subclasses have their own individual tables for additional
+  # attributes that are particular to their implementation. This is similar to what's called multi-table
+  # inheritance in Django, but instead of actual inheritance, this approach uses delegation to form the
+  # hierarchy and share responsibilities.
+  #
+  # Let's look at that entry/message/comment example using delegated types:
+  #
+  #   # Schema: entries[ id, account_id, creator_id, created_at, updated_at, entryable_type, entryable_id ]
+  #   class Entry < ApplicationRecord
+  #     belongs_to :account
+  #     belongs_to :creator
+  #     delegated_type :entryable, types: %w[ Message Comment ]
+  #   end
+  #
+  #   module Entryable
+  #     extend ActiveSupport::Concern
+  #
+  #     included do
+  #       has_one :entry, as: :entryable, touch: true
+  #     end
+  #   end
+  #
+  #   # Schema: messages[ id, subject ]
+  #   class Message < ApplicationRecord
+  #     include Entryable
+  #     has_rich_text :content
+  #   end
+  #
+  #   # Schema: comments[ id, content ]
+  #   class Comment < ApplicationRecord
+  #     include Entryable
+  #   end
+  #
+  # As you can see, neither +Message+ nor +Comment+ are meant to stand alone. Crucial metadata for both classes
+  # resides in the +Entry+ "superclass". But the +Entry+ absolutely can stand alone in terms of querying capacity
+  # in particular. You can now easily do things like:
+  #
+  #   Account.entries.order(created_at: :desc).limit(50)
+  #
+  # Which is exactly what you want when displaying both comments and messages together. The entry itself can
+  # be rendered as its delegated type easily, like so:
+  #
+  #   # entries/_entry.html.erb
+  #   <%= render "entries/entryables/#{entry.entryable_name}", entry: entry %>
+  #
+  #   # entries/entryables/_message.html.erb
+  #   <div class="message">
+  #     Posted on <%= entry.created_at %> by <%= entry.creator.name %>: <%= entry.message.content %>
+  #   </div>
+  #
+  #   # entries/entryables/_comment.html.erb
+  #   <div class="comment">
+  #     <%= entry.creator.name %> said: <%= entry.comment.content %>
+  #   </div>
+  #
+  # == Sharing behavior with concerns and controllers
+  #
+  # The entry "superclass" also serves as a perfect place to put all that shared logic that applies to both
+  # messages and comments, and which acts primarily on the shared attributes. Imagine:
+  #
+  #   class Entry < ApplicationRecord
+  #     include Eventable, Forwardable, Redeliverable
+  #   end
+  #
+  # Which allows you to have controllers for things like +ForwardsController+ and +RedeliverableController+
+  # that both act on entries, and thus provide the shared functionality to both messages and comments.
+  #
+  # == Creating new records
+  #
+  # You create a new record that uses delegated typing by creating the delegator and delegatee at the same time,
+  # like so:
+  #
+  #   Entry.create! entryable: Comment.new(content: "Hello!"), creator: Current.user
+  #
+  # If you need more complicated composition, or you need to perform dependent validation, you should build a factory
+  # method or class to take care of the complicated needs. This could be as simple as:
+  #
+  #   class Entry < ApplicationRecord
+  #     def self.create_with_comment(content, creator: Current.user)
+  #       create! entryable: Comment.new(content: content), creator: creator
+  #     end
+  #   end
+  #
+  # == Adding further delegation
+  #
+  # The delegated type shouldn't just answer the question of what the underlying class is called. In fact, that's
+  # an anti-pattern most of the time. The reason you're building this hierarchy is to take advantage of polymorphism.
+  # So here's a simple example of that:
+  #
+  #   class Entry < ApplicationRecord
+  #     delegated_type :entryable, types: %w[ Message Comment ]
+  #     delegate :title, to: :entryable
+  #   end
+  #
+  #   class Message < ApplicationRecord
+  #     def title
+  #       subject
+  #     end
+  #   end
+  #
+  #   class Comment < ApplicationRecord
+  #     def title
+  #       content.truncate(20)
+  #     end
+  #   end
+  #
+  # Now you can list a bunch of entries, call +Entry#title+, and polymorphism will provide you with the answer.
+  module DelegatedType
+    # Defines this as a class that'll delegate its type for the passed +role+ to the class references in +types+.
+    # That'll create a polymorphic +belongs_to+ relationship to that +role+, and it'll add all the delegated
+    # type convenience methods:
+    #
+    #   class Entry < ApplicationRecord
+    #     delegated_type :entryable, types: %w[ Message Comment ], dependent: :destroy
+    #   end
+    #
+    #   Entry#entryable_class # => +Message+ or +Comment+
+    #   Entry#entryable_name  # => "message" or "comment"
+    #   Entry.messages        # => Entry.where(entryable_type: "Message")
+    #   Entry#message?        # => true when entryable_type == "Message"
+    #   Entry#message         # => returns the message record, when entryable_type == "Message", otherwise nil
+    #   Entry#message_id      # => returns entryable_id, when entryable_type == "Message", otherwise nil
+    #   Entry.comments        # => Entry.where(entryable_type: "Comment")
+    #   Entry#comment?        # => true when entryable_type == "Comment"
+    #   Entry#comment         # => returns the comment record, when entryable_type == "Comment", otherwise nil
+    #   Entry#comment_id      # => returns entryable_id, when entryable_type == "Comment", otherwise nil
+    #
+    # The +options+ are passed directly to the +belongs_to+ call, so this is where you declare +dependent+ etc.
+    #
+    # You can also declare namespaced types:
+    #
+    #   class Entry < ApplicationRecord
+    #     delegated_type :entryable, types: %w[ Message Comment Access::NoticeMessage ], dependent: :destroy
+    #   end
+    #
+    #   Entry.access_notice_messages
+    #   entry.access_notice_message
+    #   entry.access_notice_message?
+    def delegated_type(role, types:, **options)
+      belongs_to role, options.delete(:scope), **options.merge(polymorphic: true)
+      define_delegated_type_methods role, types: types
+    end
+
+    private
+      def define_delegated_type_methods(role, types:)
+        role_type = "#{role}_type"
+        role_id   = "#{role}_id"
+
+        define_method "#{role}_class" do
+          public_send("#{role}_type").constantize
+        end
+
+        define_method "#{role}_name" do
+          public_send("#{role}_class").model_name.singular.inquiry
+        end
+
+        types.each do |type|
+          scope_name = type.tableize.gsub("/", "_")
+          singular   = scope_name.singularize
+          query      = "#{singular}?"
+
+          scope scope_name, -> { where(role_type => type) }
+
+          define_method query do
+            public_send(role_type) == type
+          end
+
+          define_method singular do
+            public_send(role) if public_send(query)
+          end
+
+          define_method "#{singular}_id" do
+            public_send(role_id) if public_send(query)
+          end
+        end
+      end
+  end
+end

data/lib/active_record/destroy_association_async_job.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class DestroyAssociationAsyncError < StandardError
+  end
+
+  # Job to destroy the records associated with a destroyed record in background.
+  class DestroyAssociationAsyncJob < ActiveJob::Base
+    queue_as { ActiveRecord::Base.queues[:destroy] }
+
+    discard_on ActiveJob::DeserializationError
+
+    def perform(
+      owner_model_name: nil, owner_id: nil,
+      association_class: nil, association_ids: nil, association_primary_key_column: nil,
+      ensuring_owner_was_method: nil
+    )
+      association_model = association_class.constantize
+      owner_class = owner_model_name.constantize
+      owner = owner_class.find_by(owner_class.primary_key.to_sym => owner_id)
+
+      if !owner_destroyed?(owner, ensuring_owner_was_method)
+        raise DestroyAssociationAsyncError, "owner record not destroyed"
+      end
+
+      association_model.where(association_primary_key_column => association_ids).find_each do |r|
+        r.destroy
+      end
+    end
+
+    private
+      def owner_destroyed?(owner, ensuring_owner_was_method)
+        !owner || (ensuring_owner_was_method && owner.public_send(ensuring_owner_was_method))
+      end
+  end
+end

data/lib/active_record/dynamic_matchers.rb

@@ -49,9 +49,9 @@ module ActiveRecord
 
         attr_reader :model, :name, :attribute_names
 
-        def initialize(model, name)
+        def initialize(model, method_name)
           @model           = model
-          @name            = name.to_s
+          @name            = method_name.to_s
           @attribute_names = @name.match(self.class.pattern)[1].split("_and_")
           @attribute_names.map! { |name| @model.attribute_aliases[name] || name }
         end
@@ -69,7 +69,6 @@ module ActiveRecord
         end
 
         private
-
           def body
             "#{finder}(#{attributes_hash})"
           end

data/lib/active_record/enum.rb

@@ -41,13 +41,20 @@ 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
+  #
+  # You can set the default enum value by setting +:_default+, like:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum status: [ :active, :archived ], _default: "active"
   #   end
   #
-  # Good practice is to let the first declared status be the default.
+  #   conversation = Conversation.new
+  #   conversation.status # => "active"
   #
   # Finally, it's also possible to explicitly map the relation between attribute and
   # database integer with a hash:
@@ -117,19 +124,18 @@ 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)
+        elsif value.blank?
+          nil
         else
           assert_valid_value(value)
         end
       end
 
       def deserialize(value)
-        return if value.nil?
         mapping.key(subtype.deserialize(value))
       end
 
@@ -143,15 +149,20 @@ module ActiveRecord
         end
       end
 
+      attr_reader :subtype
+
       private
-        attr_reader :name, :mapping, :subtype
+        attr_reader :name, :mapping
     end
 
     def enum(definitions)
-      klass = self
       enum_prefix = definitions.delete(:_prefix)
       enum_suffix = definitions.delete(:_suffix)
       enum_scopes = definitions.delete(:_scopes)
+
+      default = {}
+      default[:default] = definitions.delete(:_default) if definitions.key?(:_default)
+
       definitions.each do |name, values|
         assert_valid_enum_definition_values(values)
         # statuses = { }
@@ -167,57 +178,82 @@ module ActiveRecord
         detect_enum_conflict!(name, "#{name}=")
 
         attr = attribute_alias?(name) ? attribute_alias(name) : name
-        decorate_attribute_type(attr, :enum) do |subtype|
+
+        decorate_attribute_type(attr, **default) do |subtype|
           EnumType.new(attr, enum_values, subtype)
         end
 
+        value_method_names = []
         _enum_methods_module.module_eval do
+          prefix = if enum_prefix == true
+            "#{name}_"
+          elsif enum_prefix
+            "#{enum_prefix}_"
+          end
+
+          suffix = if enum_suffix == true
+            "_#{name}"
+          elsif enum_suffix
+            "_#{enum_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, enum_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, enum_scopes)
+            end
+          end
+        end
+        detect_negative_enum_conditions!(value_method_names) if enum_scopes != false
+        enum_values.freeze
+      end
+    end
+
+    private
+      class EnumMethods < Module # :nodoc:
+        def initialize(klass)
+          @klass = klass
+        end
+
+        private
+          attr_reader :klass
+
+          def define_enum_methods(name, value_method_name, value, enum_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) }
             # scope :not_active, -> { where.not(status: 0) }
             if enum_scopes != false
-              klass.send(:detect_negative_condition!, value_method_name)
-
               klass.send(:detect_enum_conflict!, name, value_method_name, true)
-              klass.scope value_method_name, -> { where(attr => value) }
+              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(attr => value) }
+              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
@@ -264,10 +300,16 @@ module ActiveRecord
         }
       end
 
-      def detect_negative_condition!(method_name)
-        if method_name.start_with?("not_") && logger
-          logger.warn "An enum element in #{self.name} uses the prefix 'not_'." \
-            " This will cause a conflict with auto generated negative scopes."
+      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

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,19 @@ 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 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
@@ -102,7 +123,7 @@ module ActiveRecord
   # Wraps the underlying database error as +cause+.
   class StatementInvalid < ActiveRecordError
     def initialize(message = nil, sql: nil, binds: nil)
-      super(message || $!.try(:message))
+      super(message || $!&.message)
       @sql = sql
       @binds = binds
     end
@@ -169,9 +190,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:
   #
@@ -183,6 +204,10 @@ module ActiveRecord
   class NoDatabaseError < StatementInvalid
   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
   # we cannot retry gracefully (e.g. inside a transaction)
   class PreparedStatementCacheExpired < StatementInvalid
@@ -220,6 +245,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
@@ -330,7 +359,7 @@ 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
 
@@ -349,30 +378,36 @@ 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
   #

data/lib/active_record/explain.rb

@@ -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_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)