activerecord 6.1.7 → 7.2.2

data/lib/active_record/database_configurations.rb

@@ -7,24 +7,78 @@ require "active_record/database_configurations/url_config"
 require "active_record/database_configurations/connection_url_resolver"
 
 module ActiveRecord
-  # ActiveRecord::DatabaseConfigurations returns an array of DatabaseConfig
-  # objects (either a HashConfig or UrlConfig) that are constructed from the
-  # application's database configuration hash or URL string.
+  # = Active Record Database Configurations
+  #
+  # +ActiveRecord::DatabaseConfigurations+ returns an array of +DatabaseConfig+
+  # objects that are constructed from the application's database
+  # configuration hash or URL string.
+  #
+  # The array of +DatabaseConfig+ objects in an application default to either a
+  # HashConfig or UrlConfig. You can retrieve your application's config by using
+  # ActiveRecord::Base.configurations.
+  #
+  # If you register a custom handler, objects will be created according to the
+  # conditions of the handler. See ::register_db_config_handler for more on
+  # registering custom handlers.
   class DatabaseConfigurations
     class InvalidConfigurationError < StandardError; end
 
     attr_reader :configurations
     delegate :any?, to: :configurations
 
+    singleton_class.attr_accessor :db_config_handlers # :nodoc:
+    self.db_config_handlers = [] # :nodoc:
+
+    # Allows an application to register a custom handler for database configuration
+    # objects. This is useful for creating a custom handler that responds to
+    # methods your application needs but Active Record doesn't implement. For
+    # example if you are using Vitess, you may want your Vitess configurations
+    # to respond to `sharded?`. To implement this define the following in an
+    # initializer:
+    #
+    #   ActiveRecord::DatabaseConfigurations.register_db_config_handler do |env_name, name, url, config|
+    #     next unless config.key?(:vitess)
+    #     VitessConfig.new(env_name, name, config)
+    #   end
+    #
+    # Note: applications must handle the condition in which custom config should be
+    # created in your handler registration otherwise all objects will use the custom
+    # handler.
+    #
+    # Then define your +VitessConfig+ to respond to the methods your application
+    # needs. It is recommended that you inherit from one of the existing
+    # database config classes to avoid having to reimplement all methods. Custom
+    # config handlers should only implement methods Active Record does not.
+    #
+    #   class VitessConfig < ActiveRecord::DatabaseConfigurations::UrlConfig
+    #     def sharded?
+    #       configuration_hash.fetch("sharded", false)
+    #     end
+    #   end
+    #
+    # For configs that have a +:vitess+ key, a +VitessConfig+ object will be
+    # created instead of a +UrlConfig+.
+    def self.register_db_config_handler(&block)
+      db_config_handlers << block
+    end
+
+    register_db_config_handler do |env_name, name, url, config|
+      if url
+        UrlConfig.new(env_name, name, url, config)
+      else
+        HashConfig.new(env_name, name, config)
+      end
+    end
+
     def initialize(configurations = {})
       @configurations = build_configs(configurations)
     end
 
     # Collects the configs for the environment and optionally the specification
-    # name passed in. To include replica configurations pass <tt>include_replicas: true</tt>.
+    # name passed in. To include replica configurations pass <tt>include_hidden: true</tt>.
     #
-    # If a name is provided a single DatabaseConfig object will be
-    # returned, otherwise an array of DatabaseConfig objects will be
+    # If a name is provided a single +DatabaseConfig+ object will be
+    # returned, otherwise an array of +DatabaseConfig+ objects will be
     # returned that corresponds with the environment and type requested.
     #
     # ==== Options
@@ -34,58 +88,49 @@ module ActiveRecord
     # * <tt>name:</tt> The db config name (i.e. primary, animals, etc.). Defaults
     #   to +nil+. If no +env_name+ is specified the config for the default env and the
     #   passed +name+ will be returned.
-    # * <tt>include_replicas:</tt> Determines whether to include replicas in
-    #   the returned list. Most of the time we're only iterating over the write
-    #   connection (i.e. migrations don't need to run for the write and read connection).
-    #   Defaults to +false+.
-    def configs_for(env_name: nil, spec_name: nil, name: nil, include_replicas: false)
-      if spec_name
-        name = spec_name
-        ActiveSupport::Deprecation.warn("The kwarg `spec_name` is deprecated in favor of `name`. `spec_name` will be removed in Rails 7.0")
-      end
-
+    # * <tt>config_key:</tt> Selects configs that contain a particular key in the configuration
+    #   hash. Useful for selecting configs that use a custom db config handler or finding
+    #   configs with hashes that contain a particular key.
+    # * <tt>include_hidden:</tt> Determines whether to include replicas and configurations
+    #   hidden by <tt>database_tasks: false</tt> in the returned list. Most of the time we're only
+    #   iterating over the primary connections (i.e. migrations don't need to run for the
+    #   write and read connection). Defaults to +false+.
+    def configs_for(env_name: nil, name: nil, config_key: nil, include_hidden: false)
       env_name ||= default_env if name
       configs = env_with_configs(env_name)
 
-      unless include_replicas
+      unless include_hidden
+        configs = configs.select do |db_config|
+          db_config.database_tasks?
+        end
+      end
+
+      if config_key
         configs = configs.select do |db_config|
-          !db_config.replica?
+          db_config.configuration_hash.key?(config_key)
         end
       end
 
       if name
         configs.find do |db_config|
-          db_config.name == name
+          db_config.name == name.to_s
         end
       else
         configs
       end
     end
 
-    # Returns the config hash that corresponds with the environment
-    #
-    # If the application has multiple databases +default_hash+ will
-    # return the first config hash for the environment.
-    #
-    #   { database: "my_db", adapter: "mysql2" }
-    def default_hash(env = default_env)
-      default = find_db_config(env)
-      default.configuration_hash if default
-    end
-    alias :[] :default_hash
-    deprecate "[]": "Use configs_for", default_hash: "Use configs_for"
-
-    # Returns a single DatabaseConfig object based on the requested environment.
+    # Returns a single +DatabaseConfig+ object based on the requested environment.
     #
     # If the application has multiple databases +find_db_config+ will return
-    # the first DatabaseConfig for the environment.
+    # the first +DatabaseConfig+ for the environment.
     def find_db_config(env)
-      configurations
-        .sort_by.with_index { |db_config, i| db_config.for_current_env? ? [0, i] : [1, i] }
-        .find do |db_config|
-          db_config.env_name == env.to_s ||
-            (db_config.for_current_env? && db_config.name == env.to_s)
-        end
+      env = env.to_s
+      configurations.find do |db_config|
+        db_config.for_current_env? && (db_config.env_name == env || db_config.name == env)
+      end || configurations.find do |db_config|
+        db_config.env_name == env
+      end
     end
 
     # A primary configuration is one that is named primary or if there is
@@ -101,17 +146,7 @@ module ActiveRecord
       first_config && name == first_config.name
     end
 
-    # Returns the DatabaseConfigurations object as a Hash.
-    def to_h
-      configurations.inject({}) do |memo, db_config|
-        memo.merge(db_config.env_name => db_config.configuration_hash.stringify_keys)
-      end
-    end
-    deprecate to_h: "You can use `ActiveRecord::Base.configurations.configs_for(env_name: 'env', name: 'primary').configuration_hash` to get the configuration hashes."
-
     # Checks if the application's configurations are empty.
-    #
-    # Aliased to blank?
     def empty?
       configurations.empty?
     end
@@ -167,7 +202,7 @@ module ActiveRecord
         return configs if configs.is_a?(Array)
 
         db_configs = configs.flat_map do |env_name, config|
-          if config.is_a?(Hash) && config.all? { |_, v| v.is_a?(Hash) }
+          if config.is_a?(Hash) && config.values.all?(Hash)
             walk_configs(env_name.to_s, config)
           else
             build_db_config_from_raw_config(env_name.to_s, "primary", config)
@@ -194,7 +229,7 @@ module ActiveRecord
           raise AdapterNotSpecified, <<~MSG
             The `#{name}` database is not configured for the `#{default_env}` environment.
 
-              Available databases configurations are:
+              Available database configurations are:
 
               #{build_configuration_sentence}
           MSG
@@ -202,7 +237,7 @@ module ActiveRecord
       end
 
       def build_configuration_sentence
-        configs = configs_for(include_replicas: true)
+        configs = configs_for(include_hidden: true)
 
         configs.group_by(&:env_name).map do |env, config|
           names = config.map(&:name)
@@ -236,15 +271,16 @@ module ActiveRecord
       end
 
       def build_db_config_from_hash(env_name, name, config)
-        if config.has_key?(:url)
-          url = config[:url]
-          config_without_url = config.dup
-          config_without_url.delete :url
+        url = config[:url]
+        config_without_url = config.dup
+        config_without_url.delete :url
 
-          UrlConfig.new(env_name, name, url, config_without_url)
-        else
-          HashConfig.new(env_name, name, config)
+        DatabaseConfigurations.db_config_handlers.reverse_each do |handler|
+          config = handler.call(env_name, name, url, config_without_url)
+          return config if config
         end
+
+        nil
       end
 
       def merge_db_environment_variables(current_env, configs)

data/lib/active_record/delegated_type.rb

@@ -3,7 +3,7 @@
 require "active_support/core_ext/string/inquiry"
 
 module ActiveRecord
-  # == Delegated types
+  # = 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,
@@ -36,7 +36,7 @@ module ActiveRecord
   #
   # 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 ]
+  #   # Schema: entries[ id, account_id, creator_id, entryable_type, entryable_id, created_at, updated_at ]
   #   class Entry < ApplicationRecord
   #     belongs_to :account
   #     belongs_to :creator
@@ -51,13 +51,12 @@ module ActiveRecord
   #     end
   #   end
   #
-  #   # Schema: messages[ id, subject ]
+  #   # Schema: messages[ id, subject, body, created_at, updated_at ]
   #   class Message < ApplicationRecord
   #     include Entryable
-  #     has_rich_text :content
   #   end
   #
-  #   # Schema: comments[ id, content ]
+  #   # Schema: comments[ id, content, created_at, updated_at ]
   #   class Comment < ApplicationRecord
   #     include Entryable
   #   end
@@ -66,7 +65,7 @@ module ActiveRecord
   # 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)
+  #   Account.find(1).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:
@@ -76,7 +75,9 @@ module ActiveRecord
   #
   #   # entries/entryables/_message.html.erb
   #   <div class="message">
-  #     Posted on <%= entry.created_at %> by <%= entry.creator.name %>: <%= entry.message.content %>
+  #     <div class="subject"><%= entry.message.subject %></div>
+  #     <p><%= entry.message.body %></p>
+  #     <i>Posted on <%= entry.created_at %> by <%= entry.creator.name %></i>
   #   </div>
   #
   #   # entries/entryables/_comment.html.erb
@@ -101,17 +102,37 @@ module ActiveRecord
   # 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
+  #   Entry.create! entryable: Comment.new(content: "Hello!"), creator: Current.user, account: Current.account
   #
   # 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
+  #     def self.create_with_comment(content, creator: Current.user, account: Current.account)
+  #       create! entryable: Comment.new(content: content), creator: creator, account: account
   #     end
   #   end
   #
+  # == Querying across records
+  #
+  # A consequence of delegated types is that querying attributes spread across multiple classes becomes slightly more
+  # tricky, but not impossible.
+  #
+  # The simplest method is to join the "superclass" to the "subclass" and apply the query parameters (i.e. <tt>#where</tt>)
+  # in appropriate places:
+  #
+  #   Comment.joins(:entry).where(comments: { content: 'Hello!' }, entry: { creator: Current.user } )
+  #
+  # For convenience, add a scope on the concern. Now all classes that implement the concern will automatically include
+  # the method:
+  #
+  #   # app/models/concerns/entryable.rb
+  #   scope :with_entry, ->(attrs) { joins(:entry).where(entry: attrs) }
+  #
+  # Now the query can be shortened significantly:
+  #
+  #   Comment.where(content: 'Hello!').with_entry(creator: Current.user)
+  #
   # == Adding further delegation
   #
   # The delegated type shouldn't just answer the question of what the underlying class is called. In fact, that's
@@ -135,7 +156,22 @@ module ActiveRecord
   #     end
   #   end
   #
-  # Now you can list a bunch of entries, call +Entry#title+, and polymorphism will provide you with the answer.
+  # Now you can list a bunch of entries, call <tt>Entry#title</tt>, and polymorphism will provide you with the answer.
+  #
+  # == Nested \Attributes
+  #
+  # Enabling nested attributes on a delegated_type association allows you to
+  # create the entry and message in one go:
+  #
+  #   class Entry < ApplicationRecord
+  #     delegated_type :entryable, types: %w[ Message Comment ]
+  #     accepts_nested_attributes_for :entryable
+  #   end
+  #
+  #   params = { entry: { entryable_type: 'Message', entryable_attributes: { subject: 'Smiling' } } }
+  #   entry = Entry.create(params[:entry])
+  #   entry.entryable.id # => 2
+  #   entry.entryable.subject # => 'Smiling'
   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
@@ -156,8 +192,6 @@ module ActiveRecord
     #   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
@@ -167,26 +201,62 @@ module ActiveRecord
     #   Entry.access_notice_messages
     #   entry.access_notice_message
     #   entry.access_notice_message?
+    #
+    # === Options
+    #
+    # The +options+ are passed directly to the +belongs_to+ call, so this is where you declare +dependent+ etc.
+    # The following options can be included to specialize the behavior of the delegated type convenience methods.
+    #
+    # [:foreign_key]
+    #   Specify the foreign key used for the convenience methods. By default this is guessed to be the passed
+    #   +role+ with an "_id" suffix. So a class that defines a
+    #   <tt>delegated_type :entryable, types: %w[ Message Comment ]</tt> association will use "entryable_id" as
+    #   the default <tt>:foreign_key</tt>.
+    # [:foreign_type]
+    #   Specify the column used to store the associated object's type. By default this is inferred to be the passed
+    #   +role+ with a "_type" suffix. A class that defines a
+    #   <tt>delegated_type :entryable, types: %w[ Message Comment ]</tt> association will use "entryable_type" as
+    #   the default <tt>:foreign_type</tt>.
+    # [:primary_key]
+    #   Specify the method that returns the primary key of associated object used for the convenience methods.
+    #   By default this is +id+.
+    #
+    # Option examples:
+    #   class Entry < ApplicationRecord
+    #     delegated_type :entryable, types: %w[ Message Comment ], primary_key: :uuid, foreign_key: :entryable_uuid
+    #   end
+    #
+    #   Entry#message_uuid      # => returns entryable_uuid, when entryable_type == "Message", otherwise nil
+    #   Entry#comment_uuid      # => returns entryable_uuid, when entryable_type == "Comment", otherwise nil
     def delegated_type(role, types:, **options)
       belongs_to role, options.delete(:scope), **options.merge(polymorphic: true)
-      define_delegated_type_methods role, types: types
+      define_delegated_type_methods role, types: types, options: options
     end
 
     private
-      def define_delegated_type_methods(role, types:)
-        role_type = "#{role}_type"
-        role_id   = "#{role}_id"
+      def define_delegated_type_methods(role, types:, options:)
+        primary_key = options[:primary_key] || "id"
+        role_type = options[:foreign_type] || "#{role}_type"
+        role_id   = options[:foreign_key] || "#{role}_id"
+
+        define_singleton_method "#{role}_types" do
+          types.map(&:to_s)
+        end
 
         define_method "#{role}_class" do
-          public_send("#{role}_type").constantize
+          public_send(role_type).constantize
         end
 
         define_method "#{role}_name" do
           public_send("#{role}_class").model_name.singular.inquiry
         end
 
+        define_method "build_#{role}" do |*params|
+          public_send("#{role}=", public_send("#{role}_class").new(*params))
+        end
+
         types.each do |type|
-          scope_name = type.tableize.gsub("/", "_")
+          scope_name = type.tableize.tr("/", "_")
           singular   = scope_name.singularize
           query      = "#{singular}?"
 
@@ -200,7 +270,7 @@ module ActiveRecord
             public_send(role) if public_send(query)
           end
 
-          define_method "#{singular}_id" do
+          define_method "#{singular}_#{primary_key}" do
             public_send(role_id) if public_send(query)
           end
         end

data/lib/active_record/deprecator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  def self.deprecator # :nodoc:
+    @deprecator ||= ActiveSupport::Deprecation.new
+  end
+end

data/lib/active_record/destroy_association_async_job.rb

@@ -4,9 +4,11 @@ module ActiveRecord
   class DestroyAssociationAsyncError < StandardError
   end
 
+  # = Active Record Destroy Association Async Job
+  #
   # Job to destroy the records associated with a destroyed record in background.
   class DestroyAssociationAsyncJob < ActiveJob::Base
-    queue_as { ActiveRecord::Base.queues[:destroy] }
+    queue_as { ActiveRecord.queues[:destroy] }
 
     discard_on ActiveJob::DeserializationError
 
@@ -17,7 +19,7 @@ module ActiveRecord
     )
       association_model = association_class.constantize
       owner_class = owner_model_name.constantize
-      owner = owner_class.find_by(owner_class.primary_key.to_sym => owner_id)
+      owner = owner_class.find_by(owner_class.primary_key => [owner_id])
 
       if !owner_destroyed?(owner, ensuring_owner_was_method)
         raise DestroyAssociationAsyncError, "owner record not destroyed"

data/lib/active_record/disable_joins_association_relation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class DisableJoinsAssociationRelation < Relation # :nodoc:
+    attr_reader :ids, :key
+
+    def initialize(klass, key, ids)
+      @ids = ids.uniq
+      @key = key
+      super(klass)
+    end
+
+    def limit(value)
+      records.take(value)
+    end
+
+    def first(limit = nil)
+      if limit
+        records.limit(limit).first
+      else
+        records.first
+      end
+    end
+
+    def load
+      super
+      records = @records
+
+      records_by_id = records.group_by do |record|
+        record[key]
+      end
+
+      records = ids.flat_map { |id| records_by_id[id] }
+      records.compact!
+
+      @records = records
+    end
+  end
+end

data/lib/active_record/dynamic_matchers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveRecord
-  module DynamicMatchers #:nodoc:
+  module DynamicMatchers # :nodoc:
     private
       def respond_to_missing?(name, _)
         if self == Base
@@ -12,12 +12,12 @@ module ActiveRecord
         end
       end
 
-      def method_missing(name, *arguments, &block)
+      def method_missing(name, ...)
         match = Method.match(self, name)
 
         if match && match.valid?
           match.define
-          send(name, *arguments, &block)
+          send(name, ...)
         else
           super
         end

data/lib/active_record/encryption/auto_filtered_parameters.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Encryption
+    class AutoFilteredParameters
+      def initialize(app)
+        @app = app
+        @attributes_by_class = Concurrent::Map.new
+        @collecting = true
+
+        install_collecting_hook
+      end
+
+      def enable
+        apply_collected_attributes
+        @collecting = false
+      end
+
+      private
+        attr_reader :app
+
+        def install_collecting_hook
+          ActiveRecord::Encryption.on_encrypted_attribute_declared do |klass, attribute|
+            attribute_was_declared(klass, attribute)
+          end
+        end
+
+        def attribute_was_declared(klass, attribute)
+          if collecting?
+            collect_for_later(klass, attribute)
+          else
+            apply_filter(klass, attribute)
+          end
+        end
+
+        def apply_collected_attributes
+          @attributes_by_class.each do |klass, attributes|
+            attributes.each do |attribute|
+              apply_filter(klass, attribute)
+            end
+          end
+        end
+
+        def collecting?
+          @collecting
+        end
+
+        def collect_for_later(klass, attribute)
+          @attributes_by_class[klass] ||= Concurrent::Array.new
+          @attributes_by_class[klass] << attribute
+        end
+
+        def apply_filter(klass, attribute)
+          filter = [("#{klass.model_name.element}" if klass.name), attribute.to_s].compact.join(".")
+          unless excluded_from_filter_parameters?(filter)
+            app.config.filter_parameters << filter unless app.config.filter_parameters.include?(filter)
+            klass.filter_attributes += [ attribute ]
+          end
+        end
+
+        def excluded_from_filter_parameters?(filter_parameter)
+          ActiveRecord::Encryption.config.excluded_from_filter_parameters.find { |excluded_filter| excluded_filter.to_s == filter_parameter }
+        end
+    end
+  end
+end