activerecord 7.0.0 → 7.1.2

data/lib/active_record/model_schema.rb

@@ -6,6 +6,13 @@ module ActiveRecord
   module ModelSchema
     extend ActiveSupport::Concern
 
+    ##
+    # :method: id_value
+    # :call-seq: id_value
+    #
+    # Returns the underlying column value for a column named "id". Useful when defining
+    # a composite primary key including an "id" column so that the value is readable.
+
     ##
     # :singleton-method: primary_key_prefix_type
     # :call-seq: primary_key_prefix_type
@@ -126,6 +133,27 @@ module ActiveRecord
     # +:immutable_string+. This setting does not affect the behavior of
     # <tt>attribute :foo, :string</tt>. Defaults to false.
 
+    ##
+    # :singleton-method: inheritance_column
+    # :call-seq: inheritance_column
+    #
+    # The name of the table column which stores the class name on single-table
+    # inheritance situations.
+    #
+    # The default inheritance column name is +type+, which means it's a
+    # reserved word inside Active Record. To be able to use single-table
+    # inheritance with another column name, or to use the column +type+ in
+    # your own model for something else, you can set +inheritance_column+:
+    #
+    #     self.inheritance_column = 'zoink'
+
+    ##
+    # :singleton-method: inheritance_column=
+    # :call-seq: inheritance_column=(column)
+    #
+    # Defines the name of the table column which will store the class name on single-table
+    # inheritance situations.
+
     included do
       class_attribute :primary_key_prefix_type, instance_writer: false
       class_attribute :table_name_prefix, instance_writer: false, default: ""
@@ -136,15 +164,6 @@ module ActiveRecord
       class_attribute :implicit_order_column, instance_accessor: false
       class_attribute :immutable_strings_by_default, instance_accessor: false
 
-      # Defines the name of the table column which will store the class name on single-table
-      # inheritance situations.
-      #
-      # The default inheritance column name is +type+, which means it's a
-      # reserved word inside Active Record. To be able to use single-table
-      # inheritance with another column name, or to use the column +type+ in
-      # your own model for something else, you can set +inheritance_column+:
-      #
-      #     self.inheritance_column = 'zoink'
       class_attribute :inheritance_column, instance_accessor: false, default: "type"
       singleton_class.class_eval do
         alias_method :_inheritance_column=, :inheritance_column=
@@ -168,8 +187,9 @@ module ActiveRecord
     #   artists, records => artists_records
     #   records, artists => artists_records
     #   music_artists, music_records => music_artists_records
+    #   music.artists, music.records => music.artists_records
     def self.derive_join_table_name(first_table, second_table) # :nodoc:
-      [first_table.to_s, second_table.to_s].sort.join("\0").gsub(/^(.*_)(.+)\0\1(.+)/, '\1\2_\3').tr("\0", "_")
+      [first_table.to_s, second_table.to_s].sort.join("\0").gsub(/^(.*[_.])(.+)\0\1(.+)/, '\1\2_\3').tr("\0", "_")
     end
 
     module ClassMethods
@@ -264,8 +284,10 @@ module ActiveRecord
 
       # Computes the table name, (re)sets it internally, and returns it.
       def reset_table_name # :nodoc:
-        self.table_name = if abstract_class?
-          superclass == Base ? nil : superclass.table_name
+        self.table_name = if self == Base
+          nil
+        elsif abstract_class?
+          superclass.table_name
         elsif superclass.abstract_class?
           superclass.table_name || compute_table_name
         else
@@ -303,11 +325,7 @@ module ActiveRecord
       # The list of columns names the model should ignore. Ignored columns won't have attribute
       # accessors defined, and won't be referenced in SQL queries.
       def ignored_columns
-        if defined?(@ignored_columns)
-          @ignored_columns
-        else
-          superclass.ignored_columns
-        end
+        @ignored_columns || superclass.ignored_columns
       end
 
       # Sets the columns names the model should ignore. Ignored columns won't have attribute
@@ -328,7 +346,7 @@ module ActiveRecord
       #     #   name       :string, limit: 255
       #     #   category   :string, limit: 255
       #
-      #     self.ignored_columns = [:category]
+      #     self.ignored_columns += [:category]
       #   end
       #
       # The schema still contains "category", but now the model omits it, so any meta-driven code or
@@ -413,6 +431,12 @@ module ActiveRecord
         @columns ||= columns_hash.values.freeze
       end
 
+      def _returning_columns_for_insert # :nodoc:
+        @_returning_columns_for_insert ||= columns.filter_map do |c|
+          c.name if connection.return_value_after_insert?(c)
+        end
+      end
+
       def attribute_types # :nodoc:
         load_schema
         @attribute_types ||= Hash.new(Type.default_value)
@@ -445,7 +469,7 @@ module ActiveRecord
       end
 
       # Returns the column object for the named attribute.
-      # Returns an +ActiveRecord::ConnectionAdapters::NullColumn+ if the
+      # Returns an ActiveRecord::ConnectionAdapters::NullColumn if the
       # named attribute does not exist.
       #
       #   class Person < ActiveRecord::Base
@@ -503,7 +527,7 @@ module ActiveRecord
       # when just after creating a table you want to populate it with some default
       # values, e.g.:
       #
-      #  class CreateJobLevels < ActiveRecord::Migration[7.0]
+      #  class CreateJobLevels < ActiveRecord::Migration[7.1]
       #    def up
       #      create_table :job_levels do |t|
       #        t.integer :id
@@ -531,35 +555,61 @@ module ActiveRecord
         initialize_find_by_cache
       end
 
+      def load_schema # :nodoc:
+        return if schema_loaded?
+        @load_schema_monitor.synchronize do
+          return if @columns_hash
+
+          load_schema!
+
+          @schema_loaded = true
+        rescue
+          reload_schema_from_cache # If the schema loading failed half way through, we must reset the state.
+          raise
+        end
+      end
+
       protected
         def initialize_load_schema_monitor
           @load_schema_monitor = Monitor.new
         end
 
+        def reload_schema_from_cache(recursive = true)
+          @_returning_columns_for_insert = nil
+          @arel_table = nil
+          @column_names = nil
+          @symbol_column_to_string_name_hash = nil
+          @attribute_types = nil
+          @content_columns = nil
+          @default_attributes = nil
+          @column_defaults = nil
+          @attributes_builder = nil
+          @columns = nil
+          @columns_hash = nil
+          @schema_loaded = false
+          @attribute_names = nil
+          @yaml_encoder = nil
+          if recursive
+            subclasses.each do |descendant|
+              descendant.send(:reload_schema_from_cache)
+            end
+          end
+        end
+
       private
         def inherited(child_class)
           super
           child_class.initialize_load_schema_monitor
+          child_class.reload_schema_from_cache(false)
+          child_class.class_eval do
+            @ignored_columns = nil
+          end
         end
 
         def schema_loaded?
           defined?(@schema_loaded) && @schema_loaded
         end
 
-        def load_schema
-          return if schema_loaded?
-          @load_schema_monitor.synchronize do
-            return if defined?(@columns_hash) && @columns_hash
-
-            load_schema!
-
-            @schema_loaded = true
-          rescue
-            reload_schema_from_cache # If the schema loading failed half way through, we must reset the state.
-            raise
-          end
-        end
-
         def load_schema!
           unless table_name
             raise ActiveRecord::TableNotSpecified, "#{self} has no table configured. Set one with #{self}.table_name="
@@ -577,25 +627,7 @@ module ActiveRecord
               default: column.default,
               user_provided_default: false
             )
-          end
-        end
-
-        def reload_schema_from_cache
-          @arel_table = nil
-          @column_names = nil
-          @symbol_column_to_string_name_hash = nil
-          @attribute_types = nil
-          @content_columns = nil
-          @default_attributes = nil
-          @column_defaults = nil
-          @attributes_builder = nil
-          @columns = nil
-          @columns_hash = nil
-          @schema_loaded = false
-          @attribute_names = nil
-          @yaml_encoder = nil
-          subclasses.each do |descendant|
-            descendant.send(:reload_schema_from_cache)
+            alias_attribute :id_value, :id if name == "id"
           end
         end
 
@@ -617,7 +649,7 @@ module ActiveRecord
 
             "#{full_table_name_prefix}#{contained}#{undecorated_table_name(model_name)}#{full_table_name_suffix}"
           else
-            # STI subclasses always use their superclass' table.
+            # STI subclasses always use their superclass's table.
             base_class.table_name
           end
         end

data/lib/active_record/nested_attributes.rb

@@ -15,7 +15,7 @@ module ActiveRecord
       class_attribute :nested_attributes_options, instance_writer: false, default: {}
     end
 
-    # = Active Record Nested Attributes
+    # = Active Record Nested \Attributes
     #
     # Nested attributes allow you to save attributes on associated records
     # through the parent. By default nested attribute updating is turned off
@@ -280,6 +280,24 @@ module ActiveRecord
     #   member = Member.new
     #   member.avatar_attributes = {icon: 'sad'}
     #   member.avatar.width # => 200
+    #
+    # === Creating forms with nested attributes
+    #
+    # Use ActionView::Helpers::FormHelper#fields_for to create form elements for
+    # nested attributes.
+    #
+    # Integration test params should reflect the structure of the form. For
+    # example:
+    #
+    #   post members_path, params: {
+    #     member: {
+    #       name: 'joe',
+    #       posts_attributes: {
+    #         '0' => { title: 'Foo' },
+    #         '1' => { title: 'Bar' }
+    #       }
+    #     }
+    #   }
     module ClassMethods
       REJECT_ALL_BLANK_PROC = proc { |attributes| attributes.all? { |key, value| key == "_destroy" || value.blank? } }
 
@@ -289,7 +307,7 @@ module ActiveRecord
       # [:allow_destroy]
       #   If true, destroys any members from the attributes hash with a
       #   <tt>_destroy</tt> key and a value that evaluates to +true+
-      #   (e.g. 1, '1', true, or 'true'). This option is off by default.
+      #   (e.g. 1, '1', true, or 'true'). This option is false by default.
       # [:reject_if]
       #   Allows you to specify a Proc or a Symbol pointing to a method
       #   that checks whether a record should be built for a certain attribute
@@ -314,11 +332,11 @@ module ActiveRecord
       #   nested attributes are going to be used when an associated record already
       #   exists. In general, an existing record may either be updated with the
       #   new set of attribute values or be replaced by a wholly new record
-      #   containing those values. By default the +:update_only+ option is +false+
+      #   containing those values. By default the +:update_only+ option is false
       #   and the nested attributes are used to update the existing record only
       #   if they include the record's <tt>:id</tt> value. Otherwise a new
       #   record will be instantiated and used to replace the existing one.
-      #   However if the +:update_only+ option is +true+, the nested attributes
+      #   However if the +:update_only+ option is true, the nested attributes
       #   are used to update the record's attributes always, regardless of
       #   whether the <tt>:id</tt> is present. The option is ignored for collection
       #   associations.
@@ -375,11 +393,11 @@ module ActiveRecord
         end
     end
 
-    # Returns ActiveRecord::AutosaveAssociation::marked_for_destruction? It's
+    # Returns ActiveRecord::AutosaveAssociation#marked_for_destruction? It's
     # used in conjunction with fields_for to build a form element for the
     # destruction of this association.
     #
-    # See ActionView::Helpers::FormHelper::fields_for for more info.
+    # See ActionView::Helpers::FormHelper#fields_for for more info.
     def _destroy
       marked_for_destruction?
     end

data/lib/active_record/normalization.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module ActiveRecord # :nodoc:
+  module Normalization
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :normalized_attributes, default: Set.new
+
+      before_validation :normalize_changed_in_place_attributes
+    end
+
+    # Normalizes a specified attribute using its declared normalizations.
+    #
+    # ==== Examples
+    #
+    #   class User < ActiveRecord::Base
+    #     normalizes :email, with: -> email { email.strip.downcase }
+    #   end
+    #
+    #   legacy_user = User.find(1)
+    #   legacy_user.email # => " CRUISE-CONTROL@EXAMPLE.COM\n"
+    #   legacy_user.normalize_attribute(:email)
+    #   legacy_user.email # => "cruise-control@example.com"
+    #   legacy_user.save
+    def normalize_attribute(name)
+      # Treat the value as a new, unnormalized value.
+      self[name] = self[name]
+    end
+
+    module ClassMethods
+      # Declares a normalization for one or more attributes. The normalization
+      # is applied when the attribute is assigned or updated, and the normalized
+      # value will be persisted to the database. The normalization is also
+      # applied to the corresponding keyword argument of query methods. This
+      # allows a record to be created and later queried using unnormalized
+      # values.
+      #
+      # However, to prevent confusion, the normalization will not be applied
+      # when the attribute is fetched from the database. This means that if a
+      # record was persisted before the normalization was declared, the record's
+      # attribute will not be normalized until either it is assigned a new
+      # value, or it is explicitly migrated via Normalization#normalize_attribute.
+      #
+      # Because the normalization may be applied multiple times, it should be
+      # _idempotent_. In other words, applying the normalization more than once
+      # should have the same result as applying it only once.
+      #
+      # By default, the normalization will not be applied to +nil+ values. This
+      # behavior can be changed with the +:apply_to_nil+ option.
+      #
+      # Be aware that if your app was created before Rails 7.1, and your app
+      # marshals instances of the targeted model (for example, when caching),
+      # then you should set ActiveRecord.marshalling_format_version to +7.1+ or
+      # higher via either <tt>config.load_defaults 7.1</tt> or
+      # <tt>config.active_record.marshalling_format_version = 7.1</tt>.
+      # Otherwise, +Marshal+ may attempt to serialize the normalization +Proc+
+      # and raise +TypeError+.
+      #
+      # ==== Options
+      #
+      # * +:with+ - Any callable object that accepts the attribute's value as
+      #   its sole argument, and returns it normalized.
+      # * +:apply_to_nil+ - Whether to apply the normalization to +nil+ values.
+      #   Defaults to +false+.
+      #
+      # ==== Examples
+      #
+      #   class User < ActiveRecord::Base
+      #     normalizes :email, with: -> email { email.strip.downcase }
+      #     normalizes :phone, with: -> phone { phone.delete("^0-9").delete_prefix("1") }
+      #   end
+      #
+      #   user = User.create(email: " CRUISE-CONTROL@EXAMPLE.COM\n")
+      #   user.email                  # => "cruise-control@example.com"
+      #
+      #   user = User.find_by(email: "\tCRUISE-CONTROL@EXAMPLE.COM ")
+      #   user.email                  # => "cruise-control@example.com"
+      #   user.email_before_type_cast # => "cruise-control@example.com"
+      #
+      #   User.where(email: "\tCRUISE-CONTROL@EXAMPLE.COM ").count         # => 1
+      #   User.where(["email = ?", "\tCRUISE-CONTROL@EXAMPLE.COM "]).count # => 0
+      #
+      #   User.exists?(email: "\tCRUISE-CONTROL@EXAMPLE.COM ")         # => true
+      #   User.exists?(["email = ?", "\tCRUISE-CONTROL@EXAMPLE.COM "]) # => false
+      #
+      #   User.normalize_value_for(:phone, "+1 (555) 867-5309") # => "5558675309"
+      def normalizes(*names, with:, apply_to_nil: false)
+        names.each do |name|
+          attribute(name) do |cast_type|
+            NormalizedValueType.new(cast_type: cast_type, normalizer: with, normalize_nil: apply_to_nil)
+          end
+        end
+
+        self.normalized_attributes += names.map(&:to_sym)
+      end
+
+      # Normalizes a given +value+ using normalizations declared for +name+.
+      #
+      # ==== Examples
+      #
+      #   class User < ActiveRecord::Base
+      #     normalizes :email, with: -> email { email.strip.downcase }
+      #   end
+      #
+      #   User.normalize_value_for(:email, " CRUISE-CONTROL@EXAMPLE.COM\n")
+      #   # => "cruise-control@example.com"
+      def normalize_value_for(name, value)
+        type_for_attribute(name).cast(value)
+      end
+    end
+
+    private
+      def normalize_changed_in_place_attributes
+        self.class.normalized_attributes.each do |name|
+          normalize_attribute(name) if attribute_changed_in_place?(name)
+        end
+      end
+
+      class NormalizedValueType < DelegateClass(ActiveModel::Type::Value) # :nodoc:
+        include ActiveModel::Type::SerializeCastValue
+
+        attr_reader :cast_type, :normalizer, :normalize_nil
+        alias :normalize_nil? :normalize_nil
+
+        def initialize(cast_type:, normalizer:, normalize_nil:)
+          @cast_type = cast_type
+          @normalizer = normalizer
+          @normalize_nil = normalize_nil
+          super(cast_type)
+        end
+
+        def cast(value)
+          normalize(super(value))
+        end
+
+        def serialize(value)
+          serialize_cast_value(cast(value))
+        end
+
+        def serialize_cast_value(value)
+          ActiveModel::Type::SerializeCastValue.serialize(cast_type, value)
+        end
+
+        def ==(other)
+          self.class == other.class &&
+            normalize_nil? == other.normalize_nil? &&
+            normalizer == other.normalizer &&
+            cast_type == other.cast_type
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, cast_type, normalizer, normalize_nil?].hash
+        end
+
+        def inspect
+          Kernel.instance_method(:inspect).bind_call(self)
+        end
+
+        private
+          def normalize(value)
+            normalizer.call(value) unless value.nil? && !normalize_nil?
+          end
+      end
+  end
+end