activerecord 7.0.0 → 7.1.0

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,
@@ -24,38 +29,6 @@ module ActiveRecord
         # The serialization format may be YAML, JSON, or any custom format using a
         # custom coder class.
         #
-        # === Serialization formats
-        #
-        #   serialize attr_name [, class_name_or_coder]
-        #
-        #                        |                           |  database storage   |
-        #   class_name_or_coder  | attribute read/write type | serialized | NULL   |
-        #   ---------------------+---------------------------+------------+--------+
-        #     <not given>        | any value that supports   |    YAML    |        |
-        #                        |   .to_yaml                |            |        |
-        #                        |                           |            |        |
-        #   Array                | Array **                  |    YAML    |  []    |
-        #                        |                           |            |        |
-        #   Hash                 | Hash **                   |    YAML    |  {}    |
-        #                        |                           |            |        |
-        #   JSON                 | any value that supports   |    JSON    |        |
-        #                        |   .to_json                |            |        |
-        #                        |                           |            |        |
-        #   <custom coder class> | any value supported by    |   custom   | custom |
-        #                        | the custom coder class    |            |        |
-        #
-        # ** If +class_name_or_coder+ is +Array+ or +Hash+, values retrieved will
-        # always be of that type, and any value assigned must be of that type or
-        # +SerializationTypeMismatch+ will be raised.
-        #
-        # ==== Custom coders
-        # A custom coder class or module may be given. This must have +self.load+
-        # and +self.dump+ class/module methods. <tt>self.dump(object)</tt> will be called
-        # to serialize an object and should return the serialized value to be
-        # stored in the database (+nil+ to store as +NULL+). <tt>self.load(string)</tt>
-        # will be called to reverse the process and load (unserialize) from the
-        # database.
-        #
         # Keep in mind that database adapters handle certain serialization tasks
         # for you. For instance: +json+ and +jsonb+ types in PostgreSQL will be
         # converted between JSON object/array syntax and Ruby +Hash+ or +Array+
@@ -67,81 +40,211 @@ module ActiveRecord
         #
         # ==== Parameters
         #
-        # * +attr_name+ - The field name that should be serialized.
-        # * +class_name_or_coder+ - Optional, may be be +Array+ or +Hash+ or
-        #   +JSON+ or a custom coder class or module which responds to +.load+
-        #   and +.dump+. See table above.
+        # * +attr_name+ - The name of the attribute to serialize.
+        # * +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
         #
-        # +default+ The default value to use when no value is provided. If this option
-        # is not passed, the previous default value (if any) will be used.
-        # Otherwise, the default will be +nil+.
+        # * +:default+ - The default value to use when no value is provided. If
+        #   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:
         #
-        # ==== 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
         #
-        #   # Serialize a preferences attribute using YAML coder.
         #   class User < ActiveRecord::Base
-        #     serialize :preferences
+        #     serialize :address, coder: Address
         #   end
         #
-        #   # Serialize preferences using JSON as coder.
+        # 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, JSON
+        #     serialize :preferences, coder: YAML
         #   end
         #
-        #   # Serialize preferences as Hash using YAML coder.
+        # ===== Serialize the +preferences+ attribute using JSON
+        #
         #   class User < ActiveRecord::Base
-        #     serialize :preferences, Hash
+        #     serialize :preferences, coder: JSON
         #   end
         #
-        #   # Serialize preferences using a custom coder.
+        # ===== Serialize the +preferences+ +Hash+ using YAML
+        #
+        #   class User < ActiveRecord::Base
+        #     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
+        #
         #   class Rot13JSON
         #     def self.rot13(string)
         #       string.tr("a-zA-Z", "n-za-mN-ZA-M")
         #     end
         #
-        #     # returns serialized string that will be stored in the database
-        #     def self.dump(object)
-        #       ActiveSupport::JSON.encode(object).rot13
+        #     # Serializes an attribute value to a string that will be stored in the database.
+        #     def self.dump(value)
+        #       rot13(ActiveSupport::JSON.dump(value))
         #     end
         #
-        #     # reverses the above, turning the serialized string from the database
-        #     # back into its original value
+        #     # Deserializes a string from the database to an attribute value.
         #     def self.load(string)
-        #       ActiveSupport::JSON.decode(string.rot13)
+        #       ActiveSupport::JSON.load(rot13(string))
         #     end
         #   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

data/lib/active_record/attribute_methods.rb

@@ -33,26 +33,94 @@ module ActiveRecord
           Base.instance_methods +
           Base.private_instance_methods -
           Base.superclass.instance_methods -
-          Base.superclass.private_instance_methods
+          Base.superclass.private_instance_methods +
+          %i[__id__ dup freeze frozen? hash object_id class clone]
         ).map { |m| -m.to_s }.to_set.freeze
       end
     end
 
     module ClassMethods
-      def inherited(child_class) # :nodoc:
-        child_class.initialize_generated_modules
-        super
-      end
-
       def initialize_generated_modules # :nodoc:
         @generated_attribute_methods = const_set(:GeneratedAttributeMethods, GeneratedAttributeMethods.new)
         private_constant :GeneratedAttributeMethods
         @attribute_methods_generated = false
+        @alias_attributes_mass_generated = false
         include @generated_attribute_methods
 
         super
       end
 
+      def alias_attribute(new_name, old_name)
+        super
+
+        if @alias_attributes_mass_generated
+          ActiveSupport::CodeGenerator.batch(generated_attribute_methods, __FILE__, __LINE__) do |code_generator|
+            generate_alias_attribute_methods(code_generator, new_name, old_name)
+          end
+        end
+      end
+
+      def eagerly_generate_alias_attribute_methods(_new_name, _old_name) # :nodoc:
+        # alias attributes in Active Record are lazily generated
+      end
+
+      def generate_alias_attributes # :nodoc:
+        superclass.generate_alias_attributes unless superclass == Base
+        return if @alias_attributes_mass_generated
+
+        generated_attribute_methods.synchronize do
+          return if @alias_attributes_mass_generated
+          ActiveSupport::CodeGenerator.batch(generated_attribute_methods, __FILE__, __LINE__) do |code_generator|
+            aliases_by_attribute_name.each do |old_name, new_names|
+              new_names.each do |new_name|
+                generate_alias_attribute_methods(code_generator, new_name, old_name)
+              end
+            end
+          end
+
+          @alias_attributes_mass_generated = true
+        end
+      end
+
+      def alias_attribute_method_definition(code_generator, pattern, new_name, old_name)
+        method_name = pattern.method_name(new_name).to_s
+        target_name = pattern.method_name(old_name).to_s
+        parameters = pattern.parameters
+        old_name = old_name.to_s
+
+        method_defined = method_defined?(target_name) || private_method_defined?(target_name)
+        manually_defined = method_defined &&
+          !self.instance_method(target_name).owner.is_a?(GeneratedAttributeMethods)
+        reserved_method_name = ::ActiveRecord::AttributeMethods.dangerous_attribute_methods.include?(target_name)
+
+        if !abstract_class? && !has_attribute?(old_name)
+          # We only need to issue this deprecation warning once, so we issue it when defining the original reader method.
+          should_warn = target_name == old_name
+          if should_warn
+            ActiveRecord.deprecator.warn(
+              "#{self} model aliases `#{old_name}`, but `#{old_name}` is not an attribute. " \
+              "Starting in Rails 7.2, alias_attribute with non-attribute targets will raise. " \
+              "Use `alias_method :#{new_name}, :#{old_name}` or define the method manually."
+            )
+          end
+          super
+        elsif manually_defined && !reserved_method_name
+          aliased_method_redefined_as_well = method_defined_within?(method_name, self)
+          return if aliased_method_redefined_as_well
+
+          ActiveRecord.deprecator.warn(
+            "#{self} model aliases `#{old_name}` and has a method called `#{target_name}` defined. " \
+            "Starting in Rails 7.2 `#{method_name}` will not be calling `#{target_name}` anymore. " \
+            "You may want to additionally define `#{method_name}` to preserve the current behavior."
+          )
+          super
+        else
+          define_proxy_call(code_generator, method_name, pattern.proxy_target, parameters, old_name,
+            namespace: :proxy_alias_attribute
+          )
+        end
+      end
+
       # Generates all the attribute related methods for columns in the database
       # accessors, mutators and query methods.
       def define_attribute_methods # :nodoc:
@@ -71,6 +139,7 @@ module ActiveRecord
         generated_attribute_methods.synchronize do
           super if defined?(@attribute_methods_generated) && @attribute_methods_generated
           @attribute_methods_generated = false
+          @alias_attributes_mass_generated = false
         end
       end
 
@@ -97,7 +166,7 @@ module ActiveRecord
           super
         else
           # If ThisClass < ... < SomeSuperClass < ... < Base and SomeSuperClass
-          # defines its own attribute method, then we don't want to overwrite that.
+          # defines its own attribute method, then we don't want to override that.
           defined = method_defined_within?(method_name, superclass, Base) &&
             ! superclass.instance_method(method_name).owner.is_a?(GeneratedAttributeMethods)
           defined || super
@@ -186,6 +255,16 @@ module ActiveRecord
       def _has_attribute?(attr_name) # :nodoc:
         attribute_types.key?(attr_name)
       end
+
+      private
+        def inherited(child_class)
+          super
+          child_class.initialize_generated_modules
+          child_class.class_eval do
+            @alias_attributes_mass_generated = false
+            @attribute_names = nil
+          end
+        end
     end
 
     # A Person object with a name attribute can ask <tt>person.respond_to?(:name)</tt>,
@@ -309,37 +388,40 @@ module ActiveRecord
       !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
     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 Date.new(2004, 12, 12)). It raises
-    # <tt>ActiveModel::MissingAttributeError</tt> if the identified attribute is missing.
-    #
-    # Note: +:id+ is always present.
+    # Returns the value of the attribute identified by +attr_name+ after it has
+    # been type cast. (For information about specific type casting behavior, see
+    # the types under ActiveModel::Type.)
     #
     #   class Person < ActiveRecord::Base
     #     belongs_to :organization
     #   end
     #
-    #   person = Person.new(name: 'Francesco', age: '22')
-    #   person[:name] # => "Francesco"
-    #   person[:age]  # => 22
+    #   person = Person.new(name: "Francesco", date_of_birth: "2004-12-12")
+    #   person[:name]            # => "Francesco"
+    #   person[:date_of_birth]   # => Date.new(2004, 12, 12)
+    #   person[:organization_id] # => nil
+    #
+    # Raises ActiveModel::MissingAttributeError if the attribute is missing.
+    # Note, however, that the +id+ attribute will never be considered missing.
     #
-    #   person = Person.select('id').first
-    #   person[:name]            # => ActiveModel::MissingAttributeError: missing attribute: name
-    #   person[:organization_id] # => ActiveModel::MissingAttributeError: missing attribute: organization_id
+    #   person = Person.select(:name).first
+    #   person[:name]            # => "Francesco"
+    #   person[:date_of_birth]   # => ActiveModel::MissingAttributeError: missing attribute 'date_of_birth' for Person
+    #   person[:organization_id] # => ActiveModel::MissingAttributeError: missing attribute 'organization_id' for Person
+    #   person[:id]              # => nil
     def [](attr_name)
       read_attribute(attr_name) { |n| missing_attribute(n, caller) }
     end
 
-    # Updates the attribute identified by <tt>attr_name</tt> with the specified +value+.
-    # (Alias for the protected #write_attribute method).
+    # Updates the attribute identified by +attr_name+ using the specified
+    # +value+. The attribute value will be type cast upon being read.
     #
     #   class Person < ActiveRecord::Base
     #   end
     #
     #   person = Person.new
-    #   person[:age] = '22'
-    #   person[:age] # => 22
-    #   person[:age].class # => Integer
+    #   person[:date_of_birth] = "2004-12-12"
+    #   person[:date_of_birth] # => Date.new(2004, 12, 12)
     def []=(attr_name, value)
       write_attribute(attr_name, value)
     end
@@ -360,10 +442,9 @@ module ActiveRecord
     #     end
     #
     #     private
-    #
-    #     def print_accessed_fields
-    #       p @posts.first.accessed_fields
-    #     end
+    #       def print_accessed_fields
+    #         p @posts.first.accessed_fields
+    #       end
     #   end
     #
     # Which allows you to quickly change your code to:
@@ -392,6 +473,7 @@ module ActiveRecord
         attribute_names &= self.class.column_names
         attribute_names.delete_if do |name|
           self.class.readonly_attribute?(name) ||
+            self.class.counter_cache_column?(name) ||
             column_for_attribute(name).virtual?
         end
       end
@@ -413,7 +495,7 @@ module ActiveRecord
           inspected_value = if value.is_a?(String) && value.length > 50
             "#{value[0, 50]}...".inspect
           elsif value.is_a?(Date) || value.is_a?(Time)
-            %("#{value.to_formatted_s(:inspect)}")
+            %("#{value.to_fs(:inspect)}")
           else
             value.inspect
           end

data/lib/active_record/attributes.rb

@@ -10,7 +10,7 @@ module ActiveRecord
     included do
       class_attribute :attributes_to_define_after_schema_loads, instance_accessor: false, default: {} # :internal:
     end
-
+    # = Active Record \Attributes
     module ClassMethods
       # Defines an attribute with a type on this model. It will override the
       # type of existing attributes if needed. This allows control over how
@@ -194,10 +194,10 @@ module ActiveRecord
       #   end
       #
       #   Product.where(price_in_bitcoins: Money.new(5, "USD"))
-      #   # => SELECT * FROM products WHERE price_in_bitcoins = 0.02230
+      #   # SELECT * FROM products WHERE price_in_bitcoins = 0.02230
       #
       #   Product.where(price_in_bitcoins: Money.new(5, "GBP"))
-      #   # => SELECT * FROM products WHERE price_in_bitcoins = 0.03412
+      #   # SELECT * FROM products WHERE price_in_bitcoins = 0.03412
       #
       # ==== Dirty Tracking
       #