activerecord 7.1.5 → 7.2.0.beta1

data/lib/active_record/database_configurations/hash_config.rb

@@ -1,53 +1,54 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActiveRecord
   class DatabaseConfigurations
-    # = Active Record Database Hash Config
+    # # Active Record Database Hash Config
     #
-    # A +HashConfig+ object is created for each database configuration entry that
-    # is created from a hash.
+    # A `HashConfig` object is created for each database configuration entry that is
+    # created from a hash.
     #
     # A hash config:
     #
-    #   { "development" => { "database" => "db_name" } }
+    #     { "development" => { "database" => "db_name" } }
     #
     # Becomes:
     #
-    #   #<ActiveRecord::DatabaseConfigurations::HashConfig:0x00007fd1acbded10
-    #     @env_name="development", @name="primary", @config={database: "db_name"}>
+    #     #<ActiveRecord::DatabaseConfigurations::HashConfig:0x00007fd1acbded10
+    #       @env_name="development", @name="primary", @config={database: "db_name"}>
     #
     # See ActiveRecord::DatabaseConfigurations for more info.
     class HashConfig < DatabaseConfig
       attr_reader :configuration_hash
 
-
-      # Initialize a new +HashConfig+ object
+      # Initialize a new `HashConfig` object
+      #
+      # #### Parameters
       #
-      # ==== Options
+      # *   `env_name` - The Rails environment, i.e. "development".
+      # *   `name` - The db config name. In a standard two-tier database configuration
+      #     this will default to "primary". In a multiple database three-tier database
+      #     configuration this corresponds to the name used in the second tier, for
+      #     example "primary_readonly".
+      # *   `configuration_hash` - The config hash. This is the hash that contains the
+      #     database adapter, name, and other important information for database
+      #     connections.
       #
-      # * <tt>:env_name</tt> - The \Rails environment, i.e. "development".
-      # * <tt>:name</tt> - The db config name. In a standard two-tier
-      #   database configuration this will default to "primary". In a multiple
-      #   database three-tier database configuration this corresponds to the name
-      #   used in the second tier, for example "primary_readonly".
-      # * <tt>:config</tt> - The config hash. This is the hash that contains the
-      #   database adapter, name, and other important information for database
-      #   connections.
       def initialize(env_name, name, configuration_hash)
         super(env_name, name)
         @configuration_hash = configuration_hash.symbolize_keys.freeze
       end
 
       # Determines whether a database configuration is for a replica / readonly
-      # connection. If the +replica+ key is present in the config, +replica?+ will
-      # return +true+.
+      # connection. If the `replica` key is present in the config, `replica?` will
+      # return `true`.
       def replica?
         configuration_hash[:replica]
       end
 
-      # The migrations paths for a database configuration. If the
-      # +migrations_paths+ key is present in the config, +migrations_paths+
-      # will return its value.
+      # The migrations paths for a database configuration. If the `migrations_paths`
+      # key is present in the config, `migrations_paths` will return its value.
       def migrations_paths
         configuration_hash[:migrations_paths]
       end
@@ -92,8 +93,8 @@ module ActiveRecord
         (configuration_hash[:checkout_timeout] || 5).to_f
       end
 
-      # +reaping_frequency+ is configurable mostly for historical reasons, but it could
-      # also be useful if someone wants a very low +idle_timeout+.
+      # `reaping_frequency` is configurable mostly for historical reasons, but it
+      # could also be useful if someone wants a very low `idle_timeout`.
       def reaping_frequency
         configuration_hash.fetch(:reaping_frequency, 60)&.to_f
       end
@@ -104,12 +105,11 @@ module ActiveRecord
       end
 
       def adapter
-        configuration_hash[:adapter]
+        configuration_hash[:adapter]&.to_s
       end
 
-      # The path to the schema cache dump file for a database.
-      # If omitted, the filename will be read from ENV or a
-      # default will be derived.
+      # The path to the schema cache dump file for a database. If omitted, the
+      # filename will be read from ENV or a default will be derived.
       def schema_cache_path
         configuration_hash[:schema_cache_path]
       end
@@ -130,14 +130,14 @@ module ActiveRecord
         Base.configurations.primary?(name)
       end
 
-      # Determines whether to dump the schema/structure files and the
-      # filename that should be used.
+      # Determines whether to dump the schema/structure files and the filename that
+      # should be used.
       #
-      # If +configuration_hash[:schema_dump]+ is set to +false+ or +nil+
-      # the schema will not be dumped.
+      # If `configuration_hash[:schema_dump]` is set to `false` or `nil` the schema
+      # will not be dumped.
       #
-      # If the config option is set that will be used. Otherwise \Rails
-      # will generate the filename from the database config name.
+      # If the config option is set that will be used. Otherwise Rails will generate
+      # the filename from the database config name.
       def schema_dump(format = ActiveRecord.schema_format)
         if configuration_hash.key?(:schema_dump)
           if config = configuration_hash[:schema_dump]
@@ -154,6 +154,10 @@ module ActiveRecord
         !replica? && !!configuration_hash.fetch(:database_tasks, true)
       end
 
+      def use_metadata_table? # :nodoc:
+        configuration_hash.fetch(:use_metadata_table, true)
+      end
+
       private
         def schema_file_type(format)
           case format

data/lib/active_record/database_configurations/url_config.rb

@@ -41,10 +41,29 @@ module ActiveRecord
         super(env_name, name, configuration_hash)
 
         @url = url
-        @configuration_hash = @configuration_hash.merge(build_url_hash).freeze
+        @configuration_hash = @configuration_hash.merge(build_url_hash)
+
+        if @configuration_hash[:schema_dump] == "false"
+          @configuration_hash[:schema_dump] = false
+        end
+
+        if @configuration_hash[:query_cache] == "false"
+          @configuration_hash[:query_cache] = false
+        end
+
+        to_boolean!(@configuration_hash, :replica)
+        to_boolean!(@configuration_hash, :database_tasks)
+
+        @configuration_hash.freeze
       end
 
       private
+        def to_boolean!(configuration_hash, key)
+          if configuration_hash[key].is_a?(String)
+            configuration_hash[key] = configuration_hash[key] != "false"
+          end
+        end
+
         # Return a Hash that can be merged into the main config that represents
         # the passed in url
         def build_url_hash

data/lib/active_record/database_configurations.rb

@@ -113,7 +113,7 @@ module ActiveRecord
 
       if name
         configs.find do |db_config|
-          db_config.name == name
+          db_config.name == name.to_s
         end
       else
         configs

data/lib/active_record/delegated_type.rb

@@ -113,6 +113,26 @@ module ActiveRecord
   #     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
@@ -219,6 +239,10 @@ module ActiveRecord
         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
         end

data/lib/active_record/dynamic_matchers.rb

@@ -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/encryptable_record.rb

@@ -84,7 +84,7 @@ module ActiveRecord
           def encrypt_attribute(name, key_provider: nil, key: nil, deterministic: false, support_unencrypted_data: nil, downcase: false, ignore_case: false, previous: [], **context_properties)
             encrypted_attributes << name.to_sym
 
-            attribute name do |cast_type|
+            decorate_attributes([name]) do |name, cast_type|
               scheme = scheme_for key_provider: key_provider, key: key, deterministic: deterministic, support_unencrypted_data: support_unencrypted_data, \
                 downcase: downcase, ignore_case: ignore_case, previous: previous, **context_properties
 
@@ -221,7 +221,7 @@ module ActiveRecord
         end
 
         def cant_modify_encrypted_attributes_when_frozen
-          self.class&.encrypted_attributes.each do |attribute|
+          self.class.encrypted_attributes.each do |attribute|
             errors.add(attribute.to_sym, "can't be modified because it is encrypted") if changed_attributes.include?(attribute)
           end
         end

data/lib/active_record/encryption/encrypted_attribute_type.rb

@@ -81,7 +81,7 @@ module ActiveRecord
           @previous_type
         end
 
-        def decrypt(value)
+        def decrypt_as_text(value)
           with_context do
             unless value.nil?
               if @default && @default == value
@@ -99,6 +99,10 @@ module ActiveRecord
           end
         end
 
+        def decrypt(value)
+          text_to_database_type decrypt_as_text(value)
+        end
+
         def try_to_deserialize_with_previous_encrypted_types(value)
           previous_types.each.with_index do |type, index|
             break type.deserialize(value)
@@ -129,12 +133,20 @@ module ActiveRecord
           encrypt(casted_value.to_s) unless casted_value.nil?
         end
 
-        def encrypt(value)
+        def encrypt_as_text(value)
           with_context do
+            if encryptor.binary? && !cast_type.binary?
+              raise Errors::Encoding, "Binary encoded data can only be stored in binary columns"
+            end
+
             encryptor.encrypt(value, **encryption_options)
           end
         end
 
+        def encrypt(value)
+          text_to_database_type encrypt_as_text(value)
+        end
+
         def encryptor
           ActiveRecord::Encryption.encryptor
         end
@@ -150,6 +162,14 @@ module ActiveRecord
         def clean_text_scheme
           @clean_text_scheme ||= ActiveRecord::Encryption::Scheme.new(downcase: downcase?, encryptor: ActiveRecord::Encryption::NullEncryptor.new)
         end
+
+        def text_to_database_type(value)
+          if value && cast_type.binary?
+            ActiveModel::Type::Binary::Data.new(value)
+          else
+            value
+          end
+        end
     end
   end
 end

data/lib/active_record/encryption/encryptor.rb

@@ -12,6 +12,14 @@ module ActiveRecord
     # It interacts with a KeyProvider for getting the keys, and delegate to
     # ActiveRecord::Encryption::Cipher the actual encryption algorithm.
     class Encryptor
+      # === Options
+      #
+      # * <tt>:compress</tt> - Boolean indicating whether records should be compressed before encryption.
+      #   Defaults to +true+.
+      def initialize(compress: true)
+        @compress = compress
+      end
+
       # Encrypts +clean_text+ and returns the encrypted result
       #
       # Internally, it will:
@@ -66,6 +74,10 @@ module ActiveRecord
         false
       end
 
+      def binary?
+        serializer.binary?
+      end
+
       private
         DECRYPT_ERRORS = [OpenSSL::Cipher::CipherError, Errors::EncryptedContentIntegrity, Errors::Decryption]
         ENCODING_ERRORS = [EncodingError, Errors::Encoding]
@@ -100,7 +112,6 @@ module ActiveRecord
         end
 
         def deserialize_message(message)
-          raise Errors::Encoding unless message.is_a?(String)
           serializer.load message
         rescue ArgumentError, TypeError, Errors::ForbiddenClass
           raise Errors::Encoding
@@ -112,13 +123,17 @@ module ActiveRecord
 
         # Under certain threshold, ZIP compression is actually worse that not compressing
         def compress_if_worth_it(string)
-          if string.bytesize > THRESHOLD_TO_JUSTIFY_COMPRESSION
+          if compress? && string.bytesize > THRESHOLD_TO_JUSTIFY_COMPRESSION
             [compress(string), true]
           else
             [string, false]
           end
         end
 
+        def compress?
+          @compress
+        end
+
         def compress(data)
           Zlib::Deflate.deflate(data).tap do |compressed_data|
             compressed_data.force_encoding(data.encoding)

data/lib/active_record/encryption/message_pack_message_serializer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "active_support/message_pack"
+
+module ActiveRecord
+  module Encryption
+    # A message serializer that serializes +Messages+ with MessagePack.
+    #
+    # The message is converted to a hash with this structure:
+    #
+    #   {
+    #     p: <payload>,
+    #     h: {
+    #       header1: value1,
+    #       header2: value2,
+    #       ...
+    #     }
+    #   }
+    #
+    # Then it is converted to the MessagePack format.
+    class MessagePackMessageSerializer
+      def dump(message)
+        raise Errors::ForbiddenClass unless message.is_a?(Message)
+        ActiveSupport::MessagePack.dump(message_to_hash(message))
+      end
+
+      def load(serialized_content)
+        data = ActiveSupport::MessagePack.load(serialized_content)
+        hash_to_message(data, 1)
+      rescue RuntimeError
+        raise Errors::Decryption
+      end
+
+      def binary?
+        true
+      end
+
+      private
+        def message_to_hash(message)
+          {
+            "p" => message.payload,
+            "h" => headers_to_hash(message.headers)
+          }
+        end
+
+        def headers_to_hash(headers)
+          headers.transform_values do |value|
+            value.is_a?(Message) ? message_to_hash(value) : value
+          end
+        end
+
+        def hash_to_message(data, level)
+          validate_message_data_format(data, level)
+          Message.new(payload: data["p"], headers: parse_properties(data["h"], level))
+        end
+
+        def validate_message_data_format(data, level)
+          if level > 2
+            raise Errors::Decryption, "More than one level of hash nesting in headers is not supported"
+          end
+
+          unless data.is_a?(Hash) && data.has_key?("p")
+            raise Errors::Decryption, "Invalid data format: hash without payload"
+          end
+        end
+
+        def parse_properties(headers, level)
+          Properties.new.tap do |properties|
+            headers&.each do |key, value|
+              properties[key] = value.is_a?(Hash) ? hash_to_message(value, level + 1) : value
+            end
+          end
+        end
+    end
+  end
+end

data/lib/active_record/encryption/message_serializer.rb

@@ -33,6 +33,10 @@ module ActiveRecord
         JSON.dump message_to_json(message)
       end
 
+      def binary?
+        false
+      end
+
       private
         def parse_message(data, level)
           validate_message_data_format(data, level)

data/lib/active_record/encryption/null_encryptor.rb

@@ -16,6 +16,10 @@ module ActiveRecord
       def encrypted?(text)
         false
       end
+
+      def binary?
+        false
+      end
     end
   end
 end

data/lib/active_record/encryption/read_only_null_encryptor.rb

@@ -19,6 +19,10 @@ module ActiveRecord
       def encrypted?(text)
         false
       end
+
+      def binary?
+        false
+      end
     end
   end
 end

data/lib/active_record/encryption.rb

@@ -53,6 +53,4 @@ module ActiveRecord
       Cipher.eager_load!
     end
   end
-
-  ActiveSupport.run_load_hooks :active_record_encryption, Encryption
 end

data/lib/active_record/enum.rb

@@ -223,6 +223,13 @@ module ActiveRecord
       options.transform_keys! { |key| :"#{key[1..-1]}" }
 
       definitions.each { |name, values| _enum(name, values, **options) }
+
+      ActiveRecord.deprecator.warn(<<~MSG)
+        Defining enums with keyword arguments is deprecated and will be removed
+        in Rails 7.3. Positional arguments should be used instead:
+
+        #{definitions.map { |name, values| "enum :#{name}, #{values}" }.join("\n")}
+      MSG
     end
 
     private
@@ -245,7 +252,9 @@ module ActiveRecord
         detect_enum_conflict!(name, name)
         detect_enum_conflict!(name, "#{name}=")
 
-        attribute(name, **options) do |subtype|
+        attribute(name, **options)
+
+        decorate_attributes([name]) do |_name, subtype|
           if subtype == ActiveModel::Type.default_value
             raise "Undeclared attribute type for enum '#{name}' in #{self.name}. Enums must be" \
               " backed by a database column or declared with an explicit type" \

data/lib/active_record/errors.rb

@@ -7,14 +7,6 @@ module ActiveRecord
   class ActiveRecordError < StandardError
   end
 
-  # DEPRECATED: Previously raised when trying to use a feature in Active Record which
-  # requires Active Job but the gem is not present. Now raises a NameError.
-  include ActiveSupport::Deprecation::DeprecatedConstantAccessor
-  DeprecatedActiveJobRequiredError = Class.new(ActiveRecordError) # :nodoc:
-  deprecate_constant "ActiveJobRequiredError", "ActiveRecord::DeprecatedActiveJobRequiredError",
-    message: "ActiveRecord::ActiveJobRequiredError has been deprecated. If Active Job is not present, a NameError will be raised instead.",
-    deprecator: ActiveRecord.deprecator
-
   # 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]
@@ -66,7 +58,7 @@ module ActiveRecord
   end
 
   # Raised when connection to the database could not been established (for example when
-  # {ActiveRecord::Base.connection=}[rdoc-ref:ConnectionHandling#connection]
+  # {ActiveRecord::Base.lease_connection=}[rdoc-ref:ConnectionHandling#lease_connection]
   # is given a +nil+ object).
   class ConnectionNotEstablished < AdapterError
     def initialize(message = nil, connection_pool: nil)
@@ -137,8 +129,10 @@ module ActiveRecord
   end
 
   # 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 cannot be saved.
+  # {ActiveRecord::Base.update_attribute!}[rdoc-ref:Persistence#update_attribute!]
+  # methods when a record is failed to validate or cannot be saved due to any of the
+  # <tt>before_*</tt> callbacks throwing +:abort+. See
+  # ActiveRecord::Callbacks for further details
   class RecordNotSaved < ActiveRecordError
     attr_reader :record
 
@@ -374,6 +368,12 @@ module ActiveRecord
   end
 
   # Raised on attempt to lazily load records that are marked as strict loading.
+  #
+  # You can resolve this error by eager loading marked records before accessing
+  # them. The
+  # {Eager Loading Associations}[https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations]
+  # guide covers solutions, such as using
+  # {ActiveRecord::Base.includes}[rdoc-ref:QueryMethods#includes].
   class StrictLoadingViolationError < ActiveRecordError
   end
 
@@ -577,4 +577,9 @@ module ActiveRecord
   # values, such as request parameters or model attributes to query methods.
   class UnknownAttributeReference < ActiveRecordError
   end
+
+  # DatabaseVersionError will be raised when the database version is not supported, or when
+  # the database version cannot be determined.
+  class DatabaseVersionError < ActiveRecordError
+  end
 end

data/lib/active_record/explain.rb

@@ -17,16 +17,17 @@ module ActiveRecord
     # Makes the adapter execute EXPLAIN for the tuples of queries and bindings.
     # Returns a formatted string ready to be logged.
     def exec_explain(queries, options = []) # :nodoc:
-      str = queries.map do |sql, binds|
-        msg = +"#{build_explain_clause(options)} #{sql}"
-        unless binds.empty?
-          msg << " "
-          msg << binds.map { |attr| render_bind(attr) }.inspect
-        end
-        msg << "\n"
-        msg << connection_explain(sql, binds, options)
-      end.join("\n")
-
+      str = with_connection do |c|
+        queries.map do |sql, binds|
+          msg = +"#{build_explain_clause(c, options)} #{sql}"
+          unless binds.empty?
+            msg << " "
+            msg << binds.map { |attr| render_bind(c, attr) }.inspect
+          end
+          msg << "\n"
+          msg << c.explain(sql, binds, options)
+        end.join("\n")
+      end
       # Overriding inspect to be more human readable, especially in the console.
       def str.inspect
         self
@@ -36,7 +37,7 @@ module ActiveRecord
     end
 
     private
-      def render_bind(attr)
+      def render_bind(connection, attr)
         if ActiveModel::Attribute === attr
           value = if attr.type.binary? && attr.value
             "<#{attr.value_for_database.to_s.bytesize} bytes of binary data>"
@@ -51,24 +52,12 @@ module ActiveRecord
         [attr&.name, value]
       end
 
-      def build_explain_clause(options = [])
+      def build_explain_clause(connection, options = [])
         if connection.respond_to?(:build_explain_clause, true)
           connection.build_explain_clause(options)
         else
           "EXPLAIN for:"
         end
       end
-
-      def connection_explain(sql, binds, options)
-        if connection.method(:explain).parameters.size == 2
-          ActiveRecord.deprecator.warn(<<~MSG.squish)
-            The current database adapter, #{connection.adapter_name}, does not support explain options.
-            To remove this warning, the adapter must implement `build_explain_clause(options = [])`.
-          MSG
-          connection.explain(sql, binds)
-        else
-          connection.explain(sql, binds, options)
-        end
-      end
   end
 end