activerecord 7.0.8.6 → 7.1.0.beta1

data/lib/active_record/attribute_methods/dirty.rb

@@ -4,6 +4,38 @@ require "active_support/core_ext/module/attribute_accessors"
 
 module ActiveRecord
   module AttributeMethods
+    # = Active Record Attribute Methods \Dirty
+    #
+    # Provides a way to track changes in your Active Record models. It adds all
+    # methods from ActiveModel::Dirty and adds database specific methods.
+    #
+    # A newly created +Person+ object is unchanged:
+    #
+    #   class Person < ActiveRecord::Base
+    #   end
+    #
+    #   person = Person.create(name: "Alisson")
+    #   person.changed? # => false
+    #
+    # Change the name:
+    #
+    #   person.name = 'Alice'
+    #   person.name_in_database          # => "Allison"
+    #   person.will_save_change_to_name? # => true
+    #   person.name_change_to_be_saved   # => ["Allison", "Alice"]
+    #   person.changes_to_save           # => {"name"=>["Allison", "Alice"]}
+    #
+    # Save the changes:
+    #
+    #   person.save
+    #   person.name_in_database        # => "Alice"
+    #   person.saved_change_to_name?   # => true
+    #   person.saved_change_to_name    # => ["Allison", "Alice"]
+    #   person.name_before_last_change # => "Allison"
+    #
+    # Similar to ActiveModel::Dirty, methods can be invoked as
+    # +saved_change_to_name?+ or by passing an argument to the generic method
+    # <tt>saved_change_to_attribute?("name")</tt>.
     module Dirty
       extend ActiveSupport::Concern
 
@@ -27,32 +59,6 @@ module ActiveRecord
         attribute_method_suffix("_change_to_be_saved", "_in_database", parameters: false)
       end
 
-      module ClassMethods
-        def partial_writes
-          ActiveSupport::Deprecation.warn(<<-MSG.squish)
-            ActiveRecord::Base.partial_writes is deprecated and will be removed in Rails 7.1.
-            Use `partial_updates` and `partial_inserts` instead.
-          MSG
-          partial_updates && partial_inserts
-        end
-
-        def partial_writes?
-          ActiveSupport::Deprecation.warn(<<-MSG.squish)
-            `ActiveRecord::Base.partial_writes?` is deprecated and will be removed in Rails 7.1.
-            Use `partial_updates?` and `partial_inserts?` instead.
-          MSG
-          partial_updates? && partial_inserts?
-        end
-
-        def partial_writes=(value)
-          ActiveSupport::Deprecation.warn(<<-MSG.squish)
-            `ActiveRecord::Base.partial_writes=` is deprecated and will be removed in Rails 7.1.
-            Use `partial_updates=` and `partial_inserts=` instead.
-          MSG
-          self.partial_updates = self.partial_inserts = value
-        end
-      end
-
       # <tt>reload</tt> the record and clears changed attributes.
       def reload(*)
         super.tap do
@@ -183,6 +189,14 @@ module ActiveRecord
       end
 
       private
+        def init_internals
+          super
+          @mutations_before_last_save = nil
+          @mutations_from_database = nil
+          @_touch_attr_names = nil
+          @_skip_dirty_tracking = nil
+        end
+
         def _touch_row(attribute_names, time)
           @_touch_attr_names = Set.new(attribute_names)
 

data/lib/active_record/attribute_methods/primary_key.rb

@@ -4,6 +4,7 @@ require "set"
 
 module ActiveRecord
   module AttributeMethods
+    # = Active Record Attribute Methods Primary Key
     module PrimaryKey
       extend ActiveSupport::Concern
 
@@ -11,41 +12,80 @@ module ActiveRecord
       # available.
       def to_key
         key = id
-        [key] if key
+        Array(key) if key
       end
 
-      # Returns the primary key column's value.
+      # Returns the primary key column's value. If the primary key is composite,
+      # returns an array of the primary key column values.
       def id
-        _read_attribute(@primary_key)
+        return _read_attribute(@primary_key) unless @primary_key.is_a?(Array)
+
+        @primary_key.map { |pk| _read_attribute(pk) }
+      end
+
+      def primary_key_values_present? # :nodoc:
+        return id.all? if self.class.composite_primary_key?
+
+        !!id
       end
 
-      # Sets the primary key column's value.
+      # Sets the primary key column's value. If the primary key is composite,
+      # raises TypeError when the set value not enumerable.
       def id=(value)
-        _write_attribute(@primary_key, value)
+        if self.class.composite_primary_key?
+          raise TypeError, "Expected value matching #{self.class.primary_key.inspect}, got #{value.inspect}." unless value.is_a?(Enumerable)
+          @primary_key.zip(value) { |attr, value| _write_attribute(attr, value) }
+        else
+          _write_attribute(@primary_key, value)
+        end
       end
 
-      # Queries the primary key column's value.
+      # Queries the primary key column's value. If the primary key is composite,
+      # all primary key column values must be queryable.
       def id?
-        query_attribute(@primary_key)
+        if self.class.composite_primary_key?
+          @primary_key.all? { |col| _query_attribute(col) }
+        else
+          _query_attribute(@primary_key)
+        end
       end
 
-      # Returns the primary key column's value before type cast.
+      # Returns the primary key column's value before type cast. If the primary key is composite,
+      # returns an array of primary key column values before type cast.
       def id_before_type_cast
-        attribute_before_type_cast(@primary_key)
+        if self.class.composite_primary_key?
+          @primary_key.map { |col| attribute_before_type_cast(col) }
+        else
+          attribute_before_type_cast(@primary_key)
+        end
       end
 
-      # Returns the primary key column's previous value.
+      # Returns the primary key column's previous value. If the primary key is composite,
+      # returns an array of primary key column previous values.
       def id_was
-        attribute_was(@primary_key)
+        if self.class.composite_primary_key?
+          @primary_key.map { |col| attribute_was(col) }
+        else
+          attribute_was(@primary_key)
+        end
       end
 
-      # Returns the primary key column's value from the database.
+      # Returns the primary key column's value from the database. If the primary key is composite,
+      # returns an array of primary key column values from database.
       def id_in_database
-        attribute_in_database(@primary_key)
+        if self.class.composite_primary_key?
+          @primary_key.map { |col| attribute_in_database(col) }
+        else
+          attribute_in_database(@primary_key)
+        end
       end
 
       def id_for_database # :nodoc:
-        @attributes[@primary_key].value_for_database
+        if self.class.composite_primary_key?
+          @primary_key.map { |col| @attributes[col].value_for_database }
+        else
+          @attributes[@primary_key].value_for_database
+        end
       end
 
       private
@@ -55,6 +95,7 @@ module ActiveRecord
 
         module ClassMethods
           ID_ATTRIBUTE_METHODS = %w(id id= id? id_before_type_cast id_was id_in_database id_for_database).to_set
+          PRIMARY_KEY_NOT_SET = BasicObject.new
 
           def instance_method_already_implemented?(method_name)
             super || primary_key && ID_ATTRIBUTE_METHODS.include?(method_name)
@@ -68,10 +109,16 @@ module ActiveRecord
           # Overwriting will negate any effect of the +primary_key_prefix_type+
           # setting, though.
           def primary_key
-            @primary_key = reset_primary_key unless defined? @primary_key
+            if PRIMARY_KEY_NOT_SET.equal?(@primary_key)
+              @primary_key = reset_primary_key
+            end
             @primary_key
           end
 
+          def composite_primary_key? # :nodoc:
+            primary_key.is_a?(Array)
+          end
+
           # Returns a quoted version of the primary key name, used to construct
           # SQL statements.
           def quoted_primary_key
@@ -93,8 +140,7 @@ module ActiveRecord
               base_name.foreign_key
             else
               if ActiveRecord::Base != self && table_exists?
-                pk = connection.schema_cache.primary_keys(table_name)
-                suppress_composite_primary_key(pk)
+                connection.schema_cache.primary_keys(table_name)
               else
                 "id"
               end
@@ -117,20 +163,26 @@ module ActiveRecord
           #
           #   Project.primary_key # => "foo_id"
           def primary_key=(value)
-            @primary_key        = value && -value.to_s
+            @primary_key        = derive_primary_key(value)
             @quoted_primary_key = nil
             @attributes_builder = nil
           end
 
           private
-            def suppress_composite_primary_key(pk)
-              return pk unless pk.is_a?(Array)
+            def derive_primary_key(value)
+              return unless value
+
+              return -value.to_s unless value.is_a?(Array)
 
-              warn <<~WARNING
-                WARNING: Active Record does not support composite primary key.
+              value.map { |v| -v.to_s }.freeze
+            end
 
-                #{table_name} has composite primary key. Composite primary key is ignored.
-              WARNING
+            def inherited(base)
+              super
+              base.class_eval do
+                @primary_key = PRIMARY_KEY_NOT_SET
+                @quoted_primary_key = nil
+              end
             end
         end
     end

data/lib/active_record/attribute_methods/query.rb

@@ -2,6 +2,7 @@
 
 module ActiveRecord
   module AttributeMethods
+    # = Active Record Attribute Methods \Query
     module Query
       extend ActiveSupport::Concern
 
@@ -12,27 +13,38 @@ module ActiveRecord
       def query_attribute(attr_name)
         value = self.public_send(attr_name)
 
-        case value
-        when true        then true
-        when false, nil  then false
-        else
-          if !type_for_attribute(attr_name) { false }
-            if Numeric === value || !value.match?(/[^0-9]/)
-              !value.to_i.zero?
+        query_cast_attribute(attr_name, value)
+      end
+
+      def _query_attribute(attr_name) # :nodoc:
+        value = self._read_attribute(attr_name.to_s)
+
+        query_cast_attribute(attr_name, value)
+      end
+
+      alias :attribute? :query_attribute
+      private :attribute?
+
+      private
+        def query_cast_attribute(attr_name, value)
+          case value
+          when true        then true
+          when false, nil  then false
+          else
+            if !type_for_attribute(attr_name) { false }
+              if Numeric === value || !value.match?(/[^0-9]/)
+                !value.to_i.zero?
+              else
+                return false if ActiveModel::Type::Boolean::FALSE_VALUES.include?(value)
+                !value.blank?
+              end
+            elsif value.respond_to?(:zero?)
+              !value.zero?
             else
-              return false if ActiveModel::Type::Boolean::FALSE_VALUES.include?(value)
               !value.blank?
             end
-          elsif value.respond_to?(:zero?)
-            !value.zero?
-          else
-            !value.blank?
           end
         end
-      end
-
-      alias :attribute? :query_attribute
-      private :attribute?
     end
   end
 end

data/lib/active_record/attribute_methods/read.rb

@@ -2,6 +2,7 @@
 
 module ActiveRecord
   module AttributeMethods
+    # = Active Record Attribute Methods \Read
     module Read
       extend ActiveSupport::Concern
 
@@ -21,15 +22,27 @@ module ActiveRecord
           end
       end
 
-      # Returns the value of the attribute identified by <tt>attr_name</tt> after
-      # it has been typecast (for example, "2004-12-12" in a date column is cast
-      # to a date object, like <tt>Date.new(2004, 12, 12)</tt>).
+      # Returns the value of the attribute identified by +attr_name+ after it
+      # has been type cast. For example, a date attribute will cast "2004-12-12"
+      # to <tt>Date.new(2004, 12, 12)</tt>. (For information about specific type
+      # casting behavior, see the types under ActiveModel::Type.)
       def read_attribute(attr_name, &block)
         name = attr_name.to_s
         name = self.class.attribute_aliases[name] || name
 
-        name = @primary_key if name == "id" && @primary_key
-        @attributes.fetch_value(name, &block)
+        return @attributes.fetch_value(name, &block) unless name == "id" && @primary_key
+
+        if self.class.composite_primary_key?
+          @attributes.fetch_value("id", &block)
+        else
+          if @primary_key != "id"
+            ActiveRecord.deprecator.warn(<<-MSG.squish)
+              Using read_attribute(:id) to read the primary key value is deprecated.
+              Use #id instead.
+            MSG
+          end
+          @attributes.fetch_value(@primary_key, &block)
+        end
       end
 
       # This method exists to avoid the expensive primary_key check internally, without

data/lib/active_record/attribute_methods/serialization.rb

@@ -2,6 +2,7 @@
 
 module ActiveRecord
   module AttributeMethods
+    # = Active Record Attribute Methods \Serialization
     module Serialization
       extend ActiveSupport::Concern
 
@@ -15,6 +16,10 @@ module ActiveRecord
         end
       end
 
+      included do
+        class_attribute :default_column_serializer, instance_accessor: false, default: Coders::YAMLColumn
+      end
+
       module ClassMethods
         # If you have an attribute that needs to be saved to the database as a
         # serialized object, and retrieved by deserializing into the same object,
@@ -36,21 +41,19 @@ module ActiveRecord
         # ==== Parameters
         #
         # * +attr_name+ - The name of the attribute to serialize.
-        # * +class_name_or_coder+ - Optional. May be one of the following:
-        #   * <em>default</em> - The attribute value will be serialized as YAML.
-        #     The attribute value must respond to +to_yaml+.
-        #   * +Array+ - The attribute value will be serialized as YAML, but an
-        #     empty +Array+ will be serialized as +NULL+. The attribute value
-        #     must be an +Array+.
-        #   * +Hash+ - The attribute value will be serialized as YAML, but an
-        #     empty +Hash+ will be serialized as +NULL+. The attribute value
-        #     must be a +Hash+.
-        #   * +JSON+ - The attribute value will be serialized as JSON. The
-        #     attribute value must respond to +to_json+.
-        #   * <em>custom coder</em> - The attribute value will be serialized
+        # * +coder+ The serializer implementation to use, e.g. +JSON+.
+        #   * The attribute value will be serialized
         #     using the coder's <tt>dump(value)</tt> method, and will be
         #     deserialized using the coder's <tt>load(string)</tt> method. The
         #     +dump+ method may return +nil+ to serialize the value as +NULL+.
+        # * +type+ - Optional. What the type of the serialized object should be.
+        #   * Attempting to serialize another type will raise an
+        #     ActiveRecord::SerializationTypeMismatch error.
+        #   * If the column is +NULL+ or starting from a new record, the default value
+        #     will set to +type.new+
+        # * +yaml+ - Optional. Yaml specific options. The allowed config is:
+        #   * +:permitted_classes+ - +Array+ with the permitted classes.
+        #   * +:unsafe_load+ - Unsafely load YAML blobs, allow YAML to load any class.
         #
         # ==== Options
         #
@@ -58,24 +61,101 @@ module ActiveRecord
         #   this option is not passed, the previous default value (if any) will
         #   be used. Otherwise, the default will be +nil+.
         #
+        # ==== Choosing a serializer
+        #
+        # While any serialization format can be used, it is recommended to carefully
+        # evaluate the properties of a serializer before using it, as migrating to
+        # another format later on can be difficult.
+        #
+        # ===== Avoid accepting arbitrary types
+        #
+        # When serializing data in a column, it is heavily recommended to make sure
+        # only expected types will be serialized. For instance some serializer like
+        # +Marshal+ or +YAML+ are capable of serializing almost any Ruby object.
+        #
+        # This can lead to unexpected types being serialized, and it is important
+        # that type serialization remains backward and forward compatible as long
+        # as some database records still contain these serialized types.
+        #
+        #   class Address
+        #     def initialize(line, city, country)
+        #       @line, @city, @country = line, city, country
+        #     end
+        #   end
+        #
+        # In the above example, if any of the +Address+ attributes is renamed,
+        # instances that were persisted before the change will be loaded with the
+        # old attributes. This problem is even worse when the serialized type comes
+        # from a dependency which doesn't expect to be serialized this way and may
+        # change its internal representation without notice.
+        #
+        # As such, it is heavily recommended to instead convert these objects into
+        # primitives of the serialization format, for example:
+        #
+        #   class Address
+        #     attr_reader :line, :city, :country
+        #
+        #     def self.load(payload)
+        #       data = YAML.safe_load(payload)
+        #       new(data["line"], data["city"], data["country"])
+        #     end
+        #
+        #     def self.dump(address)
+        #       YAML.safe_dump(
+        #         "line" => address.line,
+        #         "city" => address.city,
+        #         "country" => address.country,
+        #       )
+        #     end
+        #
+        #     def initialize(line, city, country)
+        #       @line, @city, @country = line, city, country
+        #     end
+        #   end
+        #
+        #   class User < ActiveRecord::Base
+        #     serialize :address, coder: Address
+        #   end
+        #
+        # This pattern allows to be more deliberate about what is serialized, and
+        # to evolve the format in a backward compatible way.
+        #
+        # ===== Ensure serialization stability
+        #
+        # Some serialization methods may accept some types they don't support by
+        # silently casting them to other types. This can cause bugs when the
+        # data is deserialized.
+        #
+        # For instance the +JSON+ serializer provided in the standard library will
+        # silently cast unsupported types to +String+:
+        #
+        #   >> JSON.parse(JSON.dump(Struct.new(:foo)))
+        #   => "#<Class:0x000000013090b4c0>"
+        #
         # ==== Examples
         #
         # ===== Serialize the +preferences+ attribute using YAML
         #
         #   class User < ActiveRecord::Base
-        #     serialize :preferences
+        #     serialize :preferences, coder: YAML
         #   end
         #
         # ===== Serialize the +preferences+ attribute using JSON
         #
         #   class User < ActiveRecord::Base
-        #     serialize :preferences, JSON
+        #     serialize :preferences, coder: JSON
         #   end
         #
         # ===== Serialize the +preferences+ +Hash+ using YAML
         #
         #   class User < ActiveRecord::Base
-        #     serialize :preferences, Hash
+        #     serialize :preferences, type: Hash, coder: YAML
+        #   end
+        #
+        # ===== Serializes +preferences+ to YAML, permitting select classes
+        #
+        #   class User < ActiveRecord::Base
+        #     serialize :preferences, coder: YAML, yaml: { permitted_classes: [Symbol, Time] }
         #   end
         #
         # ===== Serialize the +preferences+ attribute using a custom coder
@@ -97,35 +177,74 @@ module ActiveRecord
         #   end
         #
         #   class User < ActiveRecord::Base
-        #     serialize :preferences, Rot13JSON
+        #     serialize :preferences, coder: Rot13JSON
         #   end
         #
-        def serialize(attr_name, class_name_or_coder = Object, **options)
-          # When ::JSON is used, force it to go through the Active Support JSON encoder
-          # to ensure special objects (e.g. Active Record models) are dumped correctly
-          # using the #as_json hook.
-          coder = if class_name_or_coder == ::JSON
-            Coders::JSON
-          elsif [:load, :dump].all? { |x| class_name_or_coder.respond_to?(x) }
-            class_name_or_coder
-          else
-            Coders::YAMLColumn.new(attr_name, class_name_or_coder)
+        def serialize(attr_name, class_name_or_coder = nil, coder: nil, type: Object, yaml: {}, **options)
+          unless class_name_or_coder.nil?
+            if class_name_or_coder == ::JSON || [:load, :dump].all? { |x| class_name_or_coder.respond_to?(x) }
+              ActiveRecord.deprecator.warn(<<~MSG)
+                Passing the coder as positional argument is deprecated and will be removed in Rails 7.2.
+
+                Please pass the coder as a keyword argument:
+
+                  serialize #{attr_name.inspect}, coder: #{class_name_or_coder}
+              MSG
+              coder = class_name_or_coder
+            else
+              ActiveRecord.deprecator.warn(<<~MSG)
+                Passing the class as positional argument is deprecated and will be removed in Rails 7.2.
+
+                Please pass the class as a keyword argument:
+
+                  serialize #{attr_name.inspect}, type: #{class_name_or_coder.name}
+              MSG
+              type = class_name_or_coder
+            end
+          end
+
+          coder ||= default_column_serializer
+          unless coder
+            raise ArgumentError, <<~MSG.squish
+              missing keyword: :coder
+
+              If no default coder is configured, a coder must be provided to `serialize`.
+            MSG
           end
 
+          column_serializer = build_column_serializer(attr_name, coder, type, yaml)
+
           attribute(attr_name, **options) do |cast_type|
-            if type_incompatible_with_serialize?(cast_type, class_name_or_coder)
+            if type_incompatible_with_serialize?(cast_type, coder, type)
               raise ColumnNotSerializableError.new(attr_name, cast_type)
             end
 
             cast_type = cast_type.subtype if Type::Serialized === cast_type
-            Type::Serialized.new(cast_type, coder)
+            Type::Serialized.new(cast_type, column_serializer)
           end
         end
 
         private
-          def type_incompatible_with_serialize?(type, class_name)
-            type.is_a?(ActiveRecord::Type::Json) && class_name == ::JSON ||
-              type.respond_to?(:type_cast_array, true) && class_name == ::Array
+          def build_column_serializer(attr_name, coder, type, yaml = nil)
+            # When ::JSON is used, force it to go through the Active Support JSON encoder
+            # to ensure special objects (e.g. Active Record models) are dumped correctly
+            # using the #as_json hook.
+            coder = Coders::JSON if coder == ::JSON
+
+            if coder == ::YAML || coder == Coders::YAMLColumn
+              Coders::YAMLColumn.new(attr_name, type, **(yaml || {}))
+            elsif coder.respond_to?(:new) && !coder.respond_to?(:load)
+              coder.new(attr_name, type)
+            elsif type && type != Object
+              Coders::ColumnSerializer.new(attr_name, coder, type)
+            else
+              coder
+            end
+          end
+
+          def type_incompatible_with_serialize?(cast_type, coder, type)
+            cast_type.is_a?(ActiveRecord::Type::Json) && coder == ::JSON ||
+              cast_type.respond_to?(:type_cast_array, true) && type == ::Array
           end
       end
     end

data/lib/active_record/attribute_methods/write.rb

@@ -2,6 +2,7 @@
 
 module ActiveRecord
   module AttributeMethods
+    # = Active Record Attribute Methods \Write
     module Write
       extend ActiveSupport::Concern
 
@@ -25,9 +26,8 @@ module ActiveRecord
           end
       end
 
-      # Updates the attribute identified by <tt>attr_name</tt> with the
-      # specified +value+. Empty strings for Integer and Float columns are
-      # turned into +nil+.
+      # Updates the attribute identified by +attr_name+ using the specified
+      # +value+. The attribute value will be type cast upon being read.
       def write_attribute(attr_name, value)
         name = attr_name.to_s
         name = self.class.attribute_aliases[name] || name