Module: Mongoid::Persistence

Extended by:
ActiveSupport::Concern
Includes:
Atomic, Atomic::Positionable
Included in:
Components
Defined in:
lib/mongoid/persistence.rb,
lib/mongoid/persistence/atomic.rb,
lib/mongoid/persistence/deletion.rb,
lib/mongoid/persistence/insertion.rb,
lib/mongoid/persistence/upsertion.rb,
lib/mongoid/persistence/atomic/bit.rb,
lib/mongoid/persistence/atomic/inc.rb,
lib/mongoid/persistence/atomic/pop.rb,
lib/mongoid/persistence/operations.rb,
lib/mongoid/persistence/atomic/pull.rb,
lib/mongoid/persistence/atomic/push.rb,
lib/mongoid/persistence/atomic/sets.rb,
lib/mongoid/persistence/atomic/unset.rb,
lib/mongoid/persistence/modification.rb,
lib/mongoid/persistence/atomic/rename.rb,
lib/mongoid/persistence/atomic/pull_all.rb,
lib/mongoid/persistence/atomic/push_all.rb,
lib/mongoid/persistence/atomic/operation.rb,
lib/mongoid/persistence/atomic/add_to_set.rb,
lib/mongoid/persistence/operations/insert.rb,
lib/mongoid/persistence/operations/remove.rb,
lib/mongoid/persistence/operations/update.rb,
lib/mongoid/persistence/operations/upsert.rb,
lib/mongoid/persistence/operations/embedded/insert.rb,
lib/mongoid/persistence/operations/embedded/remove.rb

Overview

The persistence module is a mixin to provide database accessor methods for the document. These correspond to the appropriate accessors on a mongo collection and retain the same DSL.

Examples:

Sample persistence operations.

document.insert
document.update
document.upsert

Defined Under Namespace

Modules: Atomic, ClassMethods, Deletion, Insertion, Modification, Operations, Upsertion

Constant Summary

Constants included from Atomic

Atomic::UPDATES

Instance Method Summary collapse

Methods included from Atomic::Positionable

#positionally

Methods included from Atomic

#add_atomic_pull, #add_atomic_unset, #atomic_array_add_to_sets, #atomic_array_pulls, #atomic_array_pushes, #atomic_attribute_name, #atomic_delete_modifier, #atomic_insert_modifier, #atomic_path, #atomic_paths, #atomic_position, #atomic_pulls, #atomic_pushes, #atomic_selector, #atomic_sets, #atomic_unsets, #atomic_updates, #delayed_atomic_pulls, #delayed_atomic_sets, #delayed_atomic_unsets, #flag_as_destroyed, #flagged_destroys, #process_flagged_destroys

Instance Method Details

#destroy(options = {}) ⇒ true, false

Remove the document from the database with callbacks.

Examples:

Destroy a document.

document.destroy

Parameters:

  • options (Hash) (defaults to: {}) —

    Options to pass to destroy.

Returns:

  • (true, false) —

    True if successful, false if not.



32
33
34
35
36
37
38
39
 
# File 'lib/mongoid/persistence.rb', line 32

def destroy(options = {})
  self.flagged_for_destroy = true
  result = run_callbacks(:destroy) do
    remove(options)
  end
  self.flagged_for_destroy = false
  result
end

#insert(options = {}) ⇒ Document

Insert a new document into the database. Will return the document itself whether or not the save was successful.

Examples:

Insert a document.

document.insert

Parameters:

  • options (Hash) (defaults to: {}) —

    Options to pass to insert.

Returns:

  • (Document) —

    The persisted document.



50
51
52
 
# File 'lib/mongoid/persistence.rb', line 50

def insert(options = {})
  Operations.insert(self, options).persist
end

#remove(options = {}) ⇒ TrueClass Also known as: delete

Remove the document from the database.

Examples:

Remove the document.

document.remove

Parameters:

  • options (Hash) (defaults to: {}) —

    Options to pass to remove.

Returns:

  • (TrueClass) —

    True.



62
63
64
 
# File 'lib/mongoid/persistence.rb', line 62

def remove(options = {})
  Operations.remove(self, options).persist
end

#save(options = {}) ⇒ true, false

Save the document - will perform an insert if the document is new, and update if not.

Examples:

Save the document.

document.save

Parameters:

  • options (Hash) (defaults to: {}) —

    Options to pass to the save.

Returns:

  • (true, false) —

    True is success, false if not.

Since:

  • 1.0.0



78
79
80
81
82
83
84
 
# File 'lib/mongoid/persistence.rb', line 78

def save(options = {})
  if new_record?
    !insert(options).new_record?
  else
    update(options)
  end
end

#save!(options = {}) ⇒ true, false

Save the document - will perform an insert if the document is new, and update if not. If a validation error occurs an error will get raised.

Examples:

Save the document.

document.save!

Parameters:

  • options (Hash) (defaults to: {}) —

    Options to pass to the save.

Returns:

  • (true, false) —

    True if validation passed.



95
96
97
98
99
100
101
 
# File 'lib/mongoid/persistence.rb', line 95

def save!(options = {})
  unless save(options)
    self.class.fail_validate!(self) unless errors.empty?
    self.class.fail_callback!(self, :save!)
  end
  return true
end

#touch(field = nil) ⇒ true/false

Note:

This will not autobuild relations if those options are set.

Touch the document, in effect updating its updated_at timestamp and optionally the provided field to the current time. If any belongs_to relations exist with a touch option, they will be updated as well.

Examples:

Update the updated_at timestamp.

document.touch

Update the updated_at and provided timestamps.

document.touch(:audited)

Parameters:

  • field (Symbol) (defaults to: nil) —

    The name of an additional field to update.

Returns:

  • (true/false) —

    false if record is new_record otherwise true.

Since:

  • 3.0.0



120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/mongoid/persistence.rb', line 120

def touch(field = nil)
  return false if _root.new_record?
  current = Time.now
  write_attribute(:updated_at, current) if respond_to?("updated_at=")
  write_attribute(field, current) if field

  touches = touch_atomic_updates(field)
  unless touches.empty?
    selector = atomic_selector
    _root.collection.find(selector).update(positionally(selector, touches))
  end
  run_callbacks(:touch, :after)
  true
end

#update(options = {}) ⇒ true, false

Update the document in the database.

Examples:

Update an existing document.

document.update

Parameters:

  • options (Hash) (defaults to: {}) —

    Options to pass to update.

Returns:

  • (true, false) —

    True if succeeded, false if not.



143
144
145
 
# File 'lib/mongoid/persistence.rb', line 143

def update(options = {})
  Operations.update(self, options).persist
end

#update_attribute(name, value) ⇒ true, false

Update a single attribute and persist the entire document. This skips validation but fires the callbacks.

Examples:

Update the attribute.

person.update_attribute(:title, "Sir")

Parameters:

  • name (Symbol, String) —

    The name of the attribute.

  • value (Object) —

    The new value of the attribute.a

Returns:

  • (true, false) —

    True if save was successfull, false if not.

Raises:

Since:

  • 2.0.0.rc.6



162
163
164
165
166
167
168
169
 
# File 'lib/mongoid/persistence.rb', line 162

def update_attribute(name, value)
  normalized = name.to_s
  unless attribute_writable?(normalized)
    raise Errors::ReadonlyAttribute.new(normalized, value)
  end
  write_attribute(database_field_name(normalized), value)
  save(validate: false)
end

#update_attributes(attributes = {}, options = {}) ⇒ true, false

Update the document attributes in the database.

Examples:

Update the document’s attributes

document.update_attributes(:title => "Sir")

Parameters:

  • attributes (Hash) (defaults to: {}) —

    The attributes to update.

Returns:

  • (true, false) —

    True if validation passed, false if not.



179
180
181
 
# File 'lib/mongoid/persistence.rb', line 179

def update_attributes(attributes = {}, options = {})
  assign_attributes(attributes, options); save
end

#update_attributes!(attributes = {}, options = {}) ⇒ true, false

Update the document attributes in the database and raise an error if validation failed.

Examples:

Update the document’s attributes.

document.update_attributes(:title => "Sir")

Parameters:

  • attributes (Hash) (defaults to: {}) —

    The attributes to update.

Returns:

  • (true, false) —

    True if validation passed.

Raises:



194
195
196
197
198
199
200
201
 
# File 'lib/mongoid/persistence.rb', line 194

def update_attributes!(attributes = {}, options = {})
  result = update_attributes(attributes, options)
  unless result
    self.class.fail_validate!(self) unless errors.empty?
    self.class.fail_callback!(self, :update_attributes!)
  end
  result
end

#upsert(options = {}) ⇒ true

Perform an upsert of the document. If the document does not exist in the database, then Mongo will insert a new one, otherwise the fields will get overwritten with new values on the existing document.

Examples:

Upsert the document.

document.upsert

Parameters:

  • options (Hash) (defaults to: {}) —

    The validation options.

Returns:

  • (true) —

    True.

Since:

  • 3.0.0



215
216
217
 
# File 'lib/mongoid/persistence.rb', line 215

def upsert(options = {})
  Operations.upsert(self, options).persist
end