Module: ActiveRecord::AutosaveAssociation

Relationships & Source Files
Namespace Children
Modules: `AssociationBuilderExtension`, `ClassMethods`
Extension / Inclusion / Inheritance Descendants
Included In: `Base`
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `::ActiveSupport::Concern`
Defined in:	activerecord/lib/active_record/autosave_association.rb

Overview

AutosaveAssociation is a module that takes care of automatically saving associated records when their parent is saved. In addition to saving, it also destroys any associated records that were marked for destruction. (See #mark_for_destruction and #marked_for_destruction?).

Saving of the parent, its associations, and the destruction of marked associations, all happen inside a transaction. This should never leave the database in an inconsistent state.

If validations for any of the associations fail, their error messages will be applied to the parent.

Note that it also means that associations marked for destruction won’t be destroyed directly. They will however still be marked for destruction.

Note that autosave: false is not same as not declaring :autosave. When the :autosave option is not present then new association records are saved but the updated association records are not saved.

Validation

Child records are validated unless :validate is false.

Callbacks

Association with autosave option defines several callbacks on your model (around_save, before_save, after_create, after_update). Please note that callbacks are executed in the order they were defined in model. You should avoid modifying the association content before autosave callbacks are executed. Placing your callbacks after associations is usually a good practice.

One-to-one Example

class Post < ActiveRecord::Base
  has_one :author, autosave: true
end

Saving changes to the parent and its associated model can now be performed automatically and atomically:

post = Post.find(1)
post.title       # => "The current global position of migrating ducks"
post.author.name # => "alloy"

post.title = "On the migration of ducks"
post.author.name = "Eloy Duran"

post.save
post.reload
post.title       # => "On the migration of ducks"
post.author.name # => "Eloy Duran"

Destroying an associated model, as part of the parent’s save action, is as simple as marking it for destruction:

post.author.mark_for_destruction
post.author.marked_for_destruction? # => true

Note that the model is not yet removed from the database:

id = post.author.id
Author.find_by(id: id).nil? # => false

post.save
post.reload.author # => nil

Now it is removed from the database:

Author.find_by(id: id).nil? # => true

One-to-many Example

When :autosave is not declared new children are saved when their parent is saved:

class Post < ActiveRecord::Base
  has_many :comments # :autosave option is not declared
end

post = Post.new(title: 'ruby rocks')
post.comments.build(body: 'hello world')
post.save # => saves both post and comment

post = Post.create(title: 'ruby rocks')
post.comments.build(body: 'hello world')
post.save # => saves both post and comment

post = Post.create(title: 'ruby rocks')
comment = post.comments.create(body: 'hello world')
comment.body = 'hi everyone'
post.save # => saves post, but not comment

When :autosave is true all children are saved, no matter whether they are new records or not:

class Post < ActiveRecord::Base
  has_many :comments, autosave: true
end

post = Post.create(title: 'ruby rocks')
comment = post.comments.create(body: 'hello world')
comment.body = 'hi everyone'
post.comments.build(body: "good morning.")
post.save # => saves post and both comments.

Destroying one of the associated models as part of the parent’s save action is as simple as marking it for destruction:

post.comments # => [#<Comment id: 1, ...>, #<Comment id: 2, ...]>
post.comments[1].mark_for_destruction
post.comments[1].marked_for_destruction? # => true
post.comments.length # => 2

Note that the model is not yet removed from the database:

id = post.comments.last.id
Comment.find_by(id: id).nil? # => false

post.save
post.reload.comments.length # => 1

Now it is removed from the database:

Comment.find_by(id: id).nil? # => true

Caveats

Note that autosave will only trigger for already-persisted association records if the records themselves have been changed. This is to protect against SystemStackError caused by circular association validations. The one exception is if a custom validation context is used, in which case the validations will always fire on the associated records.

Class Method Summary

`::ActiveSupport::Concern` - Extended

class_methods	Define class methods from given block.
included	Evaluate given block in context of base class, so that you can write class macros here.
prepended	Evaluate given block in context of base class, so that you can write class macros here.
append_features, prepend_features

Instance Attribute Summary

#changed_for_autosave? ⇒ Boolean readonly

Returns whether or not this record has been changed in any way (including whether any of its nested autosave associations are likewise changed).
#destroyed_by_association rw

Returns the association for the parent being destroyed.
#destroyed_by_association=(reflection) rw

Records the association that is being destroyed and destroying this record in the process.
#marked_for_destruction? ⇒ Boolean readonly

Returns whether or not this record will be destroyed as part of the parent’s save transaction.
#nested_records_changed_for_autosave? ⇒ Boolean readonly private

Go through nested autosave associations that are loaded in memory (without loading any new ones), and return true if any are changed for autosave.

Instance Method Summary

#mark_for_destruction

Marks this record to be destroyed as part of the parent’s save transaction.
#reload(options = nil)

Reloads the attributes of the object as usual and clears marked_for_destruction flag.
#_ensure_no_duplicate_errors private
#_record_changed?(reflection, record, key) ⇒ Boolean private

If the record is new or it has changed, returns true.
#around_save_collection_association private

Is used as an around_save callback to check while saving a collection association whether or not the parent was a new record before saving.
#associated_records_to_validate_or_save(association, new_record, autosave) private

Returns the record for an association collection that should be validated or saved.
#association_foreign_key_changed?(reflection, record, key) ⇒ Boolean private
#association_valid?(reflection, record, index = nil) ⇒ Boolean private

Returns whether or not the association is valid and applies any errors to the parent, self, if it wasn’t.
#compute_primary_key(reflection, record) private
#init_internals private
#inverse_polymorphic_association_changed?(reflection, record) ⇒ Boolean private
#normalize_reflection_attribute(indexed_attribute, reflection, index, attribute) private
#save_belongs_to_association(reflection) private

Saves the associated record if it’s new or :autosave is enabled.
#save_collection_association(reflection) private

Saves any new associated records, or all loaded autosave associations if :autosave is enabled on the association.
#save_has_one_association(reflection) private

Saves the associated record if it’s new or :autosave is enabled on the association.
#validate_collection_association(reflection) private

Validate the associated records if :validate or :autosave is turned on for the association specified by reflection.
#validate_single_association(reflection) private

Validate the association if :validate or :autosave is turned on for the association.

DSL Calls

included

[ GitHub ]



151
152
153

# File 'activerecord/lib/active_record/autosave_association.rb', line 151


included do
  Associations::Builder::Association.extensions << AssociationBuilderExtension
end

Instance Attribute Details

#changed_for_autosave? ⇒ `Boolean` (readonly)

Returns whether or not this record has been changed in any way (including whether any of its nested autosave associations are likewise changed)

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 271


def changed_for_autosave?
  new_record? || has_changes_to_save? || marked_for_destruction? || nested_records_changed_for_autosave?
end

#destroyed_by_association (rw)

Returns the association for the parent being destroyed.

Used to avoid updating the counter cache unnecessarily.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 265


def destroyed_by_association
  @destroyed_by_association
end

#destroyed_by_association=(reflection) (rw)

Records the association that is being destroyed and destroying this record in the process.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 258


def destroyed_by_association=(reflection)
  @destroyed_by_association = reflection
end

#marked_for_destruction? ⇒ `Boolean` (readonly)

Returns whether or not this record will be destroyed as part of the parent’s save transaction.

Only useful if the :autosave option on the parent is enabled for this associated model.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 252


def marked_for_destruction?
  @marked_for_destruction
end

#nested_records_changed_for_autosave? ⇒ `Boolean` (readonly, private)

Go through nested autosave associations that are loaded in memory (without loading any new ones), and return true if any are changed for autosave. Returns false if already called to prevent an infinite loop.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 297


def nested_records_changed_for_autosave?
  @_nested_records_changed_for_autosave_already_called ||= false
  return false if @_nested_records_changed_for_autosave_already_called
  begin
    @_nested_records_changed_for_autosave_already_called = true
    self.class._reflections.values.any? do |reflection|
      if reflection.options[:autosave]
        association = association_instance_get(reflection.name)
        association && Array.wrap(association.target).any?(&:changed_for_autosave?)
      end
    end
  ensure
    @_nested_records_changed_for_autosave_already_called = false
  end
end

Instance Method Details

#_ensure_no_duplicate_errors (private)

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 551


def _ensure_no_duplicate_errors
  errors.uniq!
end

#_record_changed?(reflection, record, key) ⇒ `Boolean` (private)

If the record is new or it has changed, returns true.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 476


def _record_changed?(reflection, record, key)
  record.new_record? ||
    (association_foreign_key_changed?(reflection, record, key) ||
    inverse_polymorphic_association_changed?(reflection, record)) ||
    record.will_save_change_to_attribute?(reflection.foreign_key)
end

#around_save_collection_association (private)

Is used as an around_save callback to check while saving a collection association whether or not the parent was a new record before saving.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 371


def around_save_collection_association
  previously_new_record_before_save = (@new_record_before_save ||= false)
  @new_record_before_save = !previously_new_record_before_save && new_record?

  yield
ensure
  @new_record_before_save = previously_new_record_before_save
end

#associated_records_to_validate_or_save(association, new_record, autosave) (private)

Returns the record for an association collection that should be validated or saved. If autosave is false only new records will be returned, unless the parent is/was a new record itself.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 284


def associated_records_to_validate_or_save(association, new_record, autosave)
  if new_record || custom_validation_context?
    association && association.target
  elsif autosave
    association.target.find_all(&:changed_for_autosave?)
  else
    association.target.find_all(&:new_record?)
  end
end

#association_foreign_key_changed?(reflection, record, key) ⇒ `Boolean` (private)

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 483


def association_foreign_key_changed?(reflection, record, key)
  return false if reflection.through_reflection?

  foreign_key = Array(reflection.foreign_key)
  return false unless foreign_key.all? { |key| record._has_attribute?(key) }

  foreign_key.map { |key| record._read_attribute(key) } != Array(key)
end

#association_valid?(reflection, record, index = nil) ⇒ `Boolean` (private)

Returns whether or not the association is valid and applies any errors to the parent, self, if it wasn’t. Skips any :autosave enabled records if they’re marked_for_destruction? or destroyed.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 335


def association_valid?(reflection, record, index = nil)
  return true if record.destroyed? || (reflection.options[:autosave] && record.marked_for_destruction?)

  context = validation_context if custom_validation_context?

  unless valid = record.valid?(context)
    if reflection.options[:autosave]
      indexed_attribute = !index.nil? && (reflection.options[:index_errors] || ActiveRecord.index_nested_attribute_errors)

      record.errors.group_by_attribute.each { |attribute, errors|
        attribute = normalize_reflection_attribute(indexed_attribute, reflection, index, attribute)

        errors.each { |error|
          self.errors.import(
            error,
            attribute: attribute
          )
        }
      }
    else
      errors.add(reflection.name)
    end
  end
  valid
end

#compute_primary_key(reflection, record) (private)

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 535


def compute_primary_key(reflection, record)
  if primary_key_options = reflection.options[:primary_key]
    primary_key_options
  elsif reflection.options[:query_constraints] && (query_constraints = record.class.query_constraints_list)
    query_constraints
  elsif record.class.has_query_constraints? && !reflection.options[:foreign_key]
    record.class.query_constraints_list
  elsif record.class.composite_primary_key?
    # If record has composite primary key of shape [:<tenant_key>, :id], infer primary_key as :id
    primary_key = record.class.primary_key
    primary_key.include?("id") ? "id" : primary_key
  else
    record.class.primary_key
  end
end

#init_internals (private)

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 276


def init_internals
  super
  @_already_called = nil
end

#inverse_polymorphic_association_changed?(reflection, record) ⇒ `Boolean` (private)

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 492


def inverse_polymorphic_association_changed?(reflection, record)
  return false unless reflection.inverse_of&.polymorphic?

  class_name = record._read_attribute(reflection.inverse_of.foreign_type)

  reflection.active_record != record.class.polymorphic_class_for(class_name)
end

#mark_for_destruction

Marks this record to be destroyed as part of the parent’s save transaction. This does not actually destroy the record instantly, rather child record will be destroyed when parent.save is called.

Only useful if the :autosave option on the parent is enabled for this associated model.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 245


def mark_for_destruction
  @marked_for_destruction = true
end

#normalize_reflection_attribute(indexed_attribute, reflection, index, attribute) (private)

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 361


def normalize_reflection_attribute(indexed_attribute, reflection, index, attribute)
  if indexed_attribute
    "#{reflection.name}[#{index}].#{attribute}"
  else
    "#{reflection.name}.#{attribute}"
  end
end

#reload(options = nil)

Reloads the attributes of the object as usual and clears marked_for_destruction flag.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 234


def reload(options = nil)
  @marked_for_destruction = false
  @destroyed_by_association = nil
  super
end

#save_belongs_to_association(reflection) (private)

Saves the associated record if it’s new or :autosave is enabled.

In addition, it will destroy the association if it was marked for destruction.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 503


def save_belongs_to_association(reflection)
  association = association_instance_get(reflection.name)
  return unless association && association.loaded? && !association.stale_target?

  record = association.load_target
  if record && !record.destroyed?
    autosave = reflection.options[:autosave]

    if autosave && record.marked_for_destruction?
      foreign_key = Array(reflection.foreign_key)
      foreign_key.each { |key| self[key] = nil }
      record.destroy
    elsif autosave != false
      saved = record.save(validate: !autosave) if record.new_record? || (autosave && record.changed_for_autosave?)

      if association.updated?
        primary_key = Array(compute_primary_key(reflection, record)).map(&:to_s)
        foreign_key = Array(reflection.foreign_key)

        primary_key_foreign_key_pairs = primary_key.zip(foreign_key)
        primary_key_foreign_key_pairs.each do |primary_key, foreign_key|
          association_id = record._read_attribute(primary_key)
          self[foreign_key] = association_id unless self[foreign_key] == association_id
        end
        association.loaded!
      end

      saved if autosave
    end
  end
end

#save_collection_association(reflection) (private)

Saves any new associated records, or all loaded autosave associations if :autosave is enabled on the association.

In addition, it destroys all children that were marked for destruction with #mark_for_destruction.

This all happens inside a transaction, if the Transactions module is included into Base after the AutosaveAssociation module, which it does by default.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 388


def save_collection_association(reflection)
  if association = association_instance_get(reflection.name)
    autosave = reflection.options[:autosave]

    # By saving the instance variable in a local variable,
    # we make the whole callback re-entrant.
    new_record_before_save = @new_record_before_save

    # reconstruct the scope now that we know the owner's id
    association.reset_scope

    if records = associated_records_to_validate_or_save(association, new_record_before_save, autosave)
      if autosave
        records_to_destroy = records.select(&:marked_for_destruction?)
        records_to_destroy.each { |record| association.destroy(record) }
        records -= records_to_destroy
      end

      records.each do |record|
        next if record.destroyed?

        saved = true

        if autosave != false && (new_record_before_save || record.new_record?)
          association.set_inverse_instance(record)

          if autosave
            saved = association.insert_record(record, false)
          elsif !reflection.nested?
            association_saved = association.insert_record(record)

            if reflection.validate?
              errors.add(reflection.name) unless association_saved
              saved = association_saved
            end
          end
        elsif autosave
          saved = record.save(validate: false)
        end

        raise(RecordInvalid.new(association.owner)) unless saved
      end
    end
  end
end

#save_has_one_association(reflection) (private)

Saves the associated record if it’s new or :autosave is enabled on the association.

In addition, it will destroy the association if it was marked for destruction with #mark_for_destruction.

This all happens inside a transaction, if the Transactions module is included into Base after the AutosaveAssociation module, which it does by default.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 442


def save_has_one_association(reflection)
  association = association_instance_get(reflection.name)
  record      = association && association.load_target

  if record && !record.destroyed?
    autosave = reflection.options[:autosave]

    if autosave && record.marked_for_destruction?
      record.destroy
    elsif autosave != false
      primary_key = Array(compute_primary_key(reflection, self)).map(&:to_s)
      primary_key_value = primary_key.map { |key| _read_attribute(key) }

      if (autosave && record.changed_for_autosave?) || _record_changed?(reflection, record, primary_key_value)
        unless reflection.through_reflection
          foreign_key = Array(reflection.foreign_key)
          primary_key_foreign_key_pairs = primary_key.zip(foreign_key)

          primary_key_foreign_key_pairs.each do |primary_key, foreign_key|
            association_id = _read_attribute(primary_key)
            record[foreign_key] = association_id unless record[foreign_key] == association_id
          end
          association.set_inverse_instance(record)
        end

        saved = record.save(validate: !autosave)
        raise ActiveRecord::Rollback if !saved && autosave
        saved
      end
    end
  end
end

#validate_collection_association(reflection) (private)

Validate the associated records if :validate or :autosave is turned on for the association specified by reflection.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 324


def validate_collection_association(reflection)
  if association = association_instance_get(reflection.name)
    if records = associated_records_to_validate_or_save(association, new_record?, reflection.options[:autosave])
      records.each_with_index { |record, index| association_valid?(reflection, record, index) }
    end
  end
end

#validate_single_association(reflection) (private)

Validate the association if :validate or :autosave is turned on for the association.

[ GitHub ]

# File 'activerecord/lib/active_record/autosave_association.rb', line 315


def validate_single_association(reflection)
  association = association_instance_get(reflection.name)
  record      = association && association.reader
  association_valid?(reflection, record) if record && (record.changed_for_autosave? || custom_validation_context?)
end

Module: ActiveRecord::AutosaveAssociation

Overview

Validation

Callbacks

One-to-one Example

One-to-many Example

Caveats

Class Method Summary

::ActiveSupport::Concern - Extended

Instance Attribute Summary

Instance Method Summary

DSL Calls

included

Instance Attribute Details

#changed_for_autosave? ⇒ Boolean (readonly)

#destroyed_by_association (rw)

#destroyed_by_association=(reflection) (rw)

#marked_for_destruction? ⇒ Boolean (readonly)

#nested_records_changed_for_autosave? ⇒ Boolean (readonly, private)

Instance Method Details

#_ensure_no_duplicate_errors (private)

#_record_changed?(reflection, record, key) ⇒ Boolean (private)

#around_save_collection_association (private)

#associated_records_to_validate_or_save(association, new_record, autosave) (private)

#association_foreign_key_changed?(reflection, record, key) ⇒ Boolean (private)

#association_valid?(reflection, record, index = nil) ⇒ Boolean (private)

#compute_primary_key(reflection, record) (private)

#init_internals (private)

#inverse_polymorphic_association_changed?(reflection, record) ⇒ Boolean (private)

#mark_for_destruction

#normalize_reflection_attribute(indexed_attribute, reflection, index, attribute) (private)

#reload(options = nil)

#save_belongs_to_association(reflection) (private)

#save_collection_association(reflection) (private)

#save_has_one_association(reflection) (private)

#validate_collection_association(reflection) (private)

#validate_single_association(reflection) (private)

`::ActiveSupport::Concern` - Extended

#changed_for_autosave? ⇒ `Boolean` (readonly)

#marked_for_destruction? ⇒ `Boolean` (readonly)

#nested_records_changed_for_autosave? ⇒ `Boolean` (readonly, private)

#_record_changed?(reflection, record, key) ⇒ `Boolean` (private)

#association_foreign_key_changed?(reflection, record, key) ⇒ `Boolean` (private)

#association_valid?(reflection, record, index = nil) ⇒ `Boolean` (private)

#inverse_polymorphic_association_changed?(reflection, record) ⇒ `Boolean` (private)