activerecord 7.2.2.1 → 8.1.2

data/lib/active_record/model_schema.rb

@@ -48,7 +48,7 @@ module ActiveRecord
     # way of creating a namespace for tables in a shared database. By default, the prefix is the
     # empty string.
     #
-    # If you are organising your models within modules you can add a prefix to the models within
+    # If you are organizing your models within modules you can add a prefix to the models within
     # a namespace by defining a singleton method in the parent module called table_name_prefix which
     # returns your chosen prefix.
 
@@ -65,7 +65,7 @@ module ActiveRecord
     # Works like +table_name_prefix=+, but appends instead of prepends (set to "_basecamp" gives "projects_basecamp",
     # "people_basecamp"). By default, the suffix is the empty string.
     #
-    # If you are organising your models within modules, you can add a suffix to the models within
+    # If you are organizing your models within modules, you can add a suffix to the models within
     # a namespace by defining a singleton method in the parent module called table_name_suffix which
     # returns your chosen suffix.
 
@@ -113,17 +113,19 @@ module ActiveRecord
     # :singleton-method: implicit_order_column
     # :call-seq: implicit_order_column
     #
-    # The name of the column records are ordered by if no explicit order clause
+    # The name of the column(s) records are ordered by if no explicit order clause
     # is used during an ordered finder call. If not set the primary key is used.
 
     ##
     # :singleton-method: implicit_order_column=
     # :call-seq: implicit_order_column=(column_name)
     #
-    # Sets the column to sort records by when no explicit order clause is used
-    # during an ordered finder call. Useful when the primary key is not an
-    # auto-incrementing integer, for example when it's a UUID. Records are subsorted
-    # by the primary key if it exists to ensure deterministic results.
+    # Sets the column(s) to sort records by when no explicit order clause is used
+    # during an ordered finder call. Useful for models where the primary key isn't an
+    # auto-incrementing integer (such as UUID).
+    #
+    # By default, records are subsorted by primary key to ensure deterministic results.
+    # To disable this subsort behavior, set `implicit_order_column` to `["column_name", nil]`.
 
     ##
     # :singleton-method: immutable_strings_by_default=
@@ -179,6 +181,7 @@ module ActiveRecord
       self.protected_environments = ["production"]
 
       self.ignored_columns = [].freeze
+      self.only_columns = [].freeze
 
       delegate :type_for_attribute, :column_for_attribute, to: :class
 
@@ -276,15 +279,14 @@ module ActiveRecord
         end
 
         @table_name        = value
-        @quoted_table_name = nil
         @arel_table        = nil
         @sequence_name     = nil unless @explicit_sequence_name
         @predicate_builder = nil
       end
 
-      # Returns a quoted version of the table name, used to construct SQL statements.
+      # Returns a quoted version of the table name.
       def quoted_table_name
-        @quoted_table_name ||= adapter_class.quote_table_name(table_name)
+        adapter_class.quote_table_name(table_name)
       end
 
       # Computes the table name, (re)sets it internally, and returns it.
@@ -333,6 +335,12 @@ module ActiveRecord
         @ignored_columns || superclass.ignored_columns
       end
 
+      # The list of columns names the model should allow. Only columns are used to define
+      # attribute accessors, and are referenced in SQL queries.
+      def only_columns
+        @only_columns || superclass.only_columns
+      end
+
       # Sets the columns names the model should ignore. Ignored columns won't have attribute
       # accessors defined, and won't be referenced in SQL queries.
       #
@@ -365,10 +373,17 @@ module ActiveRecord
       #   user = Project.create!(name: "First Project")
       #   user.category # => raises NoMethodError
       def ignored_columns=(columns)
+        check_model_columns(@only_columns.present?)
         reload_schema_from_cache
         @ignored_columns = columns.map(&:to_s).freeze
       end
 
+      def only_columns=(columns)
+        check_model_columns(@ignored_columns.present?)
+        reload_schema_from_cache
+        @only_columns = columns.map(&:to_s).freeze
+      end
+
       def sequence_name
         if base_class?
           @sequence_name ||= reset_sequence_name
@@ -502,7 +517,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.2]
+      #  class CreateJobLevels < ActiveRecord::Migration[8.1]
       #    def up
       #      create_table :job_levels do |t|
       #        t.integer :id
@@ -578,6 +593,7 @@ module ActiveRecord
           child_class.reload_schema_from_cache(false)
           child_class.class_eval do
             @ignored_columns = nil
+            @only_columns = nil
           end
         end
 
@@ -591,7 +607,11 @@ module ActiveRecord
           end
 
           columns_hash = schema_cache.columns_hash(table_name)
-          columns_hash = columns_hash.except(*ignored_columns) unless ignored_columns.empty?
+          if only_columns.present?
+            columns_hash = columns_hash.slice(*only_columns)
+          elsif ignored_columns.present?
+            columns_hash = columns_hash.except(*ignored_columns)
+          end
           @columns_hash = columns_hash.freeze
 
           _default_attributes # Precompute to cache DB-dependent attribute types
@@ -621,7 +641,8 @@ module ActiveRecord
         end
 
         def type_for_column(connection, column)
-          type = connection.lookup_cast_type_from_column(column)
+          # TODO: Remove the need for a connection after we release 8.1.
+          type = column.fetch_cast_type(connection)
 
           if immutable_strings_by_default && type.respond_to?(:to_immutable_string)
             type = type.to_immutable_string
@@ -629,6 +650,10 @@ module ActiveRecord
 
           type
         end
+
+        def check_model_columns(columns_present)
+          raise ArgumentError, "You can not use both only_columns and ignored_columns in the same model." if columns_present
+        end
     end
   end
 end

data/lib/active_record/nested_attributes.rb

@@ -387,6 +387,8 @@ module ActiveRecord
           generated_association_methods.module_eval <<-eoruby, __FILE__, __LINE__ + 1
             silence_redefinition_of_method :#{association_name}_attributes=
             def #{association_name}_attributes=(attributes)
+              association = association(:#{association_name})
+              deprecated_associations_api_guard(association, __method__)
               assign_nested_attributes_for_#{type}_association(:#{association_name}, attributes)
             end
           eoruby
@@ -524,12 +526,12 @@ module ActiveRecord
             unless reject_new_record?(association_name, attributes)
               association.reader.build(attributes.except(*UNASSIGNABLE_KEYS))
             end
-          elsif existing_record = find_record_by_id(existing_records, attributes["id"])
+          elsif existing_record = find_record_by_id(association.klass, existing_records, attributes["id"])
             unless call_reject_if(association_name, attributes)
               # Make sure we are operating on the actual object which is in the association's
               # proxy_target array (either by finding it, or adding it if not found)
               # Take into account that the proxy_target may have changed due to callbacks
-              target_record = find_record_by_id(association.target, attributes["id"])
+              target_record = find_record_by_id(association.klass, association.target, attributes["id"])
               if target_record
                 existing_record = target_record
               else
@@ -621,10 +623,8 @@ module ActiveRecord
                                  model, "id", record_id)
       end
 
-      def find_record_by_id(records, id)
-        return if records.empty?
-
-        if records.first.class.composite_primary_key?
+      def find_record_by_id(klass, records, id)
+        if klass.composite_primary_key?
           id = Array(id).map(&:to_s)
           records.find { |record| Array(record.id).map(&:to_s) == id }
         else

data/lib/active_record/persistence.rb

@@ -248,18 +248,16 @@ module ActiveRecord
 
         im = Arel::InsertManager.new(arel_table)
 
-        with_connection do |c|
-          if values.empty?
-            im.insert(connection.empty_insert_statement_value(primary_key))
-          else
-            im.insert(values.transform_keys { |name| arel_table[name] })
-          end
-
-          connection.insert(
-            im, "#{self} Create", primary_key || false, primary_key_value,
-            returning: returning
-          )
+        if values.empty?
+          im.insert(connection.empty_insert_statement_value(primary_key))
+        else
+          im.insert(values.transform_keys { |name| arel_table[name] })
         end
+
+        connection.insert(
+          im, "#{self} Create", primary_key || false, primary_key_value,
+          returning: returning
+        )
       end
 
       def _update_record(values, constraints) # :nodoc:
@@ -494,6 +492,7 @@ module ActiveRecord
         becoming.instance_variable_set(:@attributes, @attributes)
         becoming.instance_variable_set(:@mutations_from_database, @mutations_from_database ||= nil)
         becoming.instance_variable_set(:@new_record, new_record?)
+        becoming.instance_variable_set(:@previously_new_record, previously_new_record?)
         becoming.instance_variable_set(:@destroyed, destroyed?)
         becoming.errors.copy!(errors)
       end
@@ -583,8 +582,8 @@ module ActiveRecord
     end
 
     # Equivalent to <code>update_columns(name => value)</code>.
-    def update_column(name, value)
-      update_columns(name => value)
+    def update_column(name, value, touch: nil)
+      update_columns(name => value, touch: touch)
     end
 
     # Updates the attributes directly in the database issuing an UPDATE SQL
@@ -598,11 +597,25 @@ module ActiveRecord
     #
     # * \Validations are skipped.
     # * \Callbacks are skipped.
-    # * +updated_at+/+updated_on+ are not updated.
+    # * +updated_at+/+updated_on+ are updated if the +touch+ option is set to +true+.
     # * However, attributes are serialized with the same rules as ActiveRecord::Relation#update_all
     #
     # This method raises an ActiveRecord::ActiveRecordError when called on new
     # objects, or when at least one of the attributes is marked as readonly.
+    #
+    # ==== Parameters
+    #
+    # * <tt>:touch</tt> option - Touch the timestamp columns when updating.
+    # * If attribute names are passed, they are updated along with +updated_at+/+updated_on+ attributes.
+    #
+    # ==== Examples
+    #
+    #   # Update a single attribute.
+    #   user.update_columns(last_request_at: Time.current)
+    #
+    #   # Update with touch option.
+    #   user.update_columns(last_request_at: Time.current, touch: true)
+
     def update_columns(attributes)
       raise ActiveRecordError, "cannot update a new record" if new_record?
       raise ActiveRecordError, "cannot update a destroyed record" if destroyed?
@@ -614,6 +627,15 @@ module ActiveRecord
         verify_readonly_attribute(name) || name
       end
 
+      touch = attributes.delete("touch")
+      if touch
+        names = touch if touch != true
+        names = Array.wrap(names)
+        options = names.extract_options!
+        touch_updates = self.class.touch_attributes_with_time(*names, **options)
+        attributes.with_defaults!(touch_updates) unless touch_updates.empty?
+      end
+
       update_constraints = _query_constraints_hash
       attributes = attributes.each_with_object({}) do |(k, v), h|
         h[k] = @attributes.write_cast_value(k, v)
@@ -642,8 +664,15 @@ module ActiveRecord
     # This means that any other modified attributes will still be dirty.
     # Validations and callbacks are skipped. Supports the +touch+ option from
     # +update_counters+, see that for more.
+    #
+    # This method raises an ActiveRecord::ActiveRecordError when called on new
+    # objects, or when at least one of the attributes is marked as readonly.
+    #
     # Returns +self+.
     def increment!(attribute, by = 1, touch: nil)
+      raise ActiveRecordError, "cannot update a new record" if new_record?
+      raise ActiveRecordError, "cannot update a destroyed record" if destroyed?
+
       increment(attribute, by)
       change = public_send(attribute) - (public_send(:"#{attribute}_in_database") || 0)
       self.class.update_counters(id, attribute => change, touch: touch)
@@ -812,159 +841,159 @@ module ActiveRecord
       end
     end
 
-  private
-    def init_internals
-      super
-      @_trigger_destroy_callback = @_trigger_update_callback = nil
-      @previously_new_record = false
-    end
+    private
+      def init_internals
+        super
+        @_trigger_destroy_callback = @_trigger_update_callback = nil
+        @previously_new_record = false
+      end
 
-    def strict_loaded_associations
-      @association_cache.find_all do |_, assoc|
-        assoc.owner.strict_loading? && !assoc.owner.strict_loading_n_plus_one_only?
-      end.map(&:first)
-    end
+      def strict_loaded_associations
+        @association_cache.find_all do |_, assoc|
+          assoc.owner.strict_loading? && !assoc.owner.strict_loading_n_plus_one_only?
+        end.map(&:first)
+      end
 
-    def _find_record(options)
-      all_queries = options ? options[:all_queries] : nil
-      base = self.class.all(all_queries: all_queries).preload(strict_loaded_associations)
+      def _find_record(options)
+        all_queries = options ? options[:all_queries] : nil
+        base = self.class.all(all_queries: all_queries).preload(strict_loaded_associations)
 
-      if options && options[:lock]
-        base.lock(options[:lock]).find_by!(_in_memory_query_constraints_hash)
-      else
-        base.find_by!(_in_memory_query_constraints_hash)
+        if options && options[:lock]
+          base.lock(options[:lock]).find_by!(_in_memory_query_constraints_hash)
+        else
+          base.find_by!(_in_memory_query_constraints_hash)
+        end
       end
-    end
 
-    def _in_memory_query_constraints_hash
-      if self.class.query_constraints_list.nil?
-        { @primary_key => id }
-      else
-        self.class.query_constraints_list.index_with do |column_name|
-          attribute(column_name)
+      def _in_memory_query_constraints_hash
+        if self.class.query_constraints_list.nil?
+          { @primary_key => id }
+        else
+          self.class.query_constraints_list.index_with do |column_name|
+            attribute(column_name)
+          end
         end
       end
-    end
 
-    def apply_scoping?(options)
-      !(options && options[:unscoped]) &&
-        (self.class.default_scopes?(all_queries: true) || self.class.global_current_scope)
-    end
+      def apply_scoping?(options)
+        !(options && options[:unscoped]) &&
+          (self.class.default_scopes?(all_queries: true) || self.class.global_current_scope)
+      end
 
-    def _query_constraints_hash
-      if self.class.query_constraints_list.nil?
-        { @primary_key => id_in_database }
-      else
-        self.class.query_constraints_list.index_with do |column_name|
-          attribute_in_database(column_name)
+      def _query_constraints_hash
+        if self.class.query_constraints_list.nil?
+          { @primary_key => id_in_database }
+        else
+          self.class.query_constraints_list.index_with do |column_name|
+            attribute_in_database(column_name)
+          end
         end
       end
-    end
 
-    # A hook to be overridden by association modules.
-    def destroy_associations
-    end
-
-    def destroy_row
-      _delete_row
-    end
-
-    def _delete_row
-      self.class._delete_record(_query_constraints_hash)
-    end
+      # A hook to be overridden by association modules.
+      def destroy_associations
+      end
 
-    def _touch_row(attribute_names, time)
-      time ||= current_time_from_proper_timezone
+      def destroy_row
+        _delete_row
+      end
 
-      attribute_names.each do |attr_name|
-        _write_attribute(attr_name, time)
+      def _delete_row
+        self.class._delete_record(_query_constraints_hash)
       end
 
-      _update_row(attribute_names, "touch")
-    end
+      def _touch_row(attribute_names, time)
+        time ||= current_time_from_proper_timezone
 
-    def _update_row(attribute_names, attempted_action = "update")
-      self.class._update_record(
-        attributes_with_values(attribute_names),
-        _query_constraints_hash
-      )
-    end
+        attribute_names.each do |attr_name|
+          _write_attribute(attr_name, time)
+        end
 
-    def create_or_update(**, &block)
-      _raise_readonly_record_error if readonly?
-      return false if destroyed?
-      result = new_record? ? _create_record(&block) : _update_record(&block)
-      result != false
-    end
+        _update_row(attribute_names, "touch")
+      end
 
-    # Updates the associated record with values matching those of the instance attributes.
-    # Returns the number of affected rows.
-    def _update_record(attribute_names = self.attribute_names)
-      attribute_names = attributes_for_update(attribute_names)
+      def _update_row(attribute_names, attempted_action = "update")
+        self.class._update_record(
+          attributes_with_values(attribute_names),
+          _query_constraints_hash
+        )
+      end
 
-      if attribute_names.empty?
-        affected_rows = 0
-        @_trigger_update_callback = true
-      else
-        affected_rows = _update_row(attribute_names)
-        @_trigger_update_callback = affected_rows == 1
+      def create_or_update(**, &block)
+        _raise_readonly_record_error if readonly?
+        return false if destroyed?
+        result = new_record? ? _create_record(&block) : _update_record(&block)
+        result != false
       end
 
-      @previously_new_record = false
+      # Updates the associated record with values matching those of the instance attributes.
+      # Returns the number of affected rows.
+      def _update_record(attribute_names = self.attribute_names)
+        attribute_names = attributes_for_update(attribute_names)
+
+        if attribute_names.empty?
+          affected_rows = 0
+          @_trigger_update_callback = true
+        else
+          affected_rows = _update_row(attribute_names)
+          @_trigger_update_callback = affected_rows == 1
+        end
 
-      yield(self) if block_given?
+        @previously_new_record = false
 
-      affected_rows
-    end
+        yield(self) if block_given?
 
-    # Creates a record with values matching those of the instance attributes
-    # and returns its id.
-    def _create_record(attribute_names = self.attribute_names)
-      attribute_names = attributes_for_create(attribute_names)
+        affected_rows
+      end
 
-      self.class.with_connection do |connection|
-        returning_columns = self.class._returning_columns_for_insert(connection)
+      # Creates a record with values matching those of the instance attributes
+      # and returns its id.
+      def _create_record(attribute_names = self.attribute_names)
+        attribute_names = attributes_for_create(attribute_names)
 
-        returning_values = self.class._insert_record(
-          connection,
-          attributes_with_values(attribute_names),
-          returning_columns
-        )
+        self.class.with_connection do |connection|
+          returning_columns = self.class._returning_columns_for_insert(connection)
 
-        returning_columns.zip(returning_values).each do |column, value|
-          _write_attribute(column, value) if !_read_attribute(column)
-        end if returning_values
-      end
+          returning_values = self.class._insert_record(
+            connection,
+            attributes_with_values(attribute_names),
+            returning_columns
+          )
 
-      @new_record = false
-      @previously_new_record = true
+          returning_columns.zip(returning_values).each do |column, value|
+            _write_attribute(column, type_for_attribute(column).deserialize(value)) if !_read_attribute(column)
+          end if returning_values
+        end
 
-      yield(self) if block_given?
+        @new_record = false
+        @previously_new_record = true
 
-      id
-    end
+        yield(self) if block_given?
 
-    def verify_readonly_attribute(name)
-      raise ActiveRecordError, "#{name} is marked as readonly" if self.class.readonly_attribute?(name)
-    end
+        id
+      end
 
-    def _raise_record_not_destroyed
-      @_association_destroy_exception ||= nil
-      key = self.class.primary_key
-      raise @_association_destroy_exception || RecordNotDestroyed.new("Failed to destroy #{self.class} with #{key}=#{id}", self)
-    ensure
-      @_association_destroy_exception = nil
-    end
+      def verify_readonly_attribute(name)
+        raise ActiveRecordError, "#{name} is marked as readonly" if self.class.readonly_attribute?(name)
+      end
 
-    def _raise_readonly_record_error
-      raise ReadOnlyRecord, "#{self.class} is marked as readonly"
-    end
+      def _raise_record_not_destroyed
+        @_association_destroy_exception ||= nil
+        key = self.class.primary_key
+        raise @_association_destroy_exception || RecordNotDestroyed.new("Failed to destroy #{self.class} with #{key}=#{id}", self)
+      ensure
+        @_association_destroy_exception = nil
+      end
 
-    def _raise_record_not_touched_error
-      raise ActiveRecordError, <<~MSG.squish
-        Cannot touch on a new or destroyed record object. Consider using
-        persisted?, new_record?, or destroyed? before touching.
-      MSG
-    end
+      def _raise_readonly_record_error
+        raise ReadOnlyRecord, "#{self.class} is marked as readonly"
+      end
+
+      def _raise_record_not_touched_error
+        raise ActiveRecordError, <<~MSG.squish
+          Cannot touch on a new or destroyed record object. Consider using
+          persisted?, new_record?, or destroyed? before touching.
+        MSG
+      end
   end
 end

data/lib/active_record/query_cache.rb

@@ -3,6 +3,7 @@
 module ActiveRecord
   # = Active Record Query Cache
   class QueryCache
+    # ActiveRecord::Base extends this module, so these methods are available in models.
     module ClassMethods
       # Enable the query cache within the block if Active Record is configured.
       # If it's not, it will execute the given block.
@@ -20,11 +21,15 @@ module ActiveRecord
         end
       end
 
-      # Disable the query cache within the block if Active Record is configured.
-      # If it's not, it will execute the given block.
+      # Runs the block with the query cache disabled.
+      #
+      # If the query cache was enabled before the block was executed, it is
+      # enabled again after it.
       #
-      # Set <tt>dirties: false</tt> to prevent query caches on all connections from being cleared by write operations.
-      # (By default, write operations dirty all connections' query caches in case they are replicas whose cache would now be outdated.)
+      # Set <tt>dirties: false</tt> to prevent query caches on all connections
+      # from being cleared by write operations. (By default, write operations
+      # dirty all connections' query caches in case they are replicas whose
+      # cache would now be outdated.)
       def uncached(dirties: true, &block)
         if connected? || !configurations.empty?
           connection_pool.disable_query_cache(dirties: dirties, &block)
@@ -34,22 +39,24 @@ module ActiveRecord
       end
     end
 
-    def self.run
-      ActiveRecord::Base.connection_handler.each_connection_pool.reject(&:query_cache_enabled).each do |pool|
-        next if pool.db_config&.query_cache == false
-        pool.enable_query_cache!
+    module ExecutorHooks # :nodoc:
+      def self.run
+        ActiveRecord::Base.connection_handler.each_connection_pool.reject(&:query_cache_enabled).each do |pool|
+          next if pool.db_config&.query_cache == false
+          pool.enable_query_cache!
+        end
       end
-    end
 
-    def self.complete(pools)
-      pools.each do |pool|
-        pool.disable_query_cache!
-        pool.clear_query_cache
+      def self.complete(pools)
+        pools.each do |pool|
+          pool.disable_query_cache!
+          pool.clear_query_cache
+        end
       end
     end
 
-    def self.install_executor_hooks(executor = ActiveSupport::Executor)
-      executor.register_hook(self)
+    def self.install_executor_hooks(executor = ActiveSupport::Executor) # :nodoc:
+      executor.register_hook(ExecutorHooks)
     end
   end
 end