module Mongoid::Persistence
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.
@example Sample persistence operations.
document.insert document.update document.upsert
Constants
- LIST_OPERATIONS
The atomic operations that deal with arrays or sets in the db.
@since 4.0.0
Public Instance Methods
Remove the document from the database with callbacks.
@example Destroy a document.
document.destroy
@param [ Hash ] options Options to pass to destroy.
@return [ true, false ] True if successful, false if not.
# File lib/mongoid/persistence.rb, line 36 def destroy(options = {}) self.flagged_for_destroy = true result = run_callbacks(:destroy) do remove(options) end self.flagged_for_destroy = false result end
Insert a new document into the database. Will return the document itself whether or not the save was successful.
@example Insert a document.
document.insert
@param [ Hash ] options Options to pass to insert.
@return [ Document ] The persisted document.
# File lib/mongoid/persistence.rb, line 54 def insert(options = {}) Operations.insert(self, options).persist end
Remove the document from the database.
@example Remove the document.
document.remove
@param [ Hash ] options Options to pass to remove.
@return [ TrueClass ] True.
# File lib/mongoid/persistence.rb, line 66 def remove(options = {}) Operations.remove(self, options).persist end
Save the document - will perform an insert if the document is new, and update if not.
@example Save the document.
document.save
@param [ Hash ] options Options to pass to the save.
@return [ true, false ] True is success, false if not.
@since 1.0.0
# File lib/mongoid/persistence.rb, line 82 def save(options = {}) if new_record? !insert(options).new_record? else update(options) end end
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.
@example Save the document.
document.save!
@param [ Hash ] options Options to pass to the save.
@return [ true, false ] True if validation passed.
# File lib/mongoid/persistence.rb, line 99 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 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.
@example Update the updated_at timestamp.
document.touch
@example Update the updated_at and provided timestamps.
document.touch(:audited)
@note This will not autobuild relations if those options are set.
@param [ Symbol ] field The name of an additional field to update.
@return [ true/false ] false if record is new_record otherwise true.
@since 3.0.0
# File lib/mongoid/persistence.rb, line 124 def touch(field = nil) return false if _root.new_record? current = Time.now field = database_field_name(field) 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 the document in the database.
@example Update an existing document.
document.update
@param [ Hash ] options Options to pass to update.
@return [ true, false ] True if succeeded, false if not.
# File lib/mongoid/persistence.rb, line 148 def update(options = {}) Operations.update(self, options).persist end
Update a single attribute and persist the entire document. This skips validation but fires the callbacks.
@example Update the attribute.
person.update_attribute(:title, "Sir")
@param [ Symbol, String ] name The name of the attribute. @param [ Object ] value The new value of the attribute.a
@raise [ Errors::ReadonlyAttribute ] If the field cannot be changed due
to being flagged as reaodnly.
@return [ true, false ] True if save was successfull, false if not.
@since 2.0.0.rc.6
# File lib/mongoid/persistence.rb, line 167 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 the document attributes in the database.
@example Update the document's attributes
document.update_attributes(:title => "Sir")
@param [ Hash ] attributes The attributes to update.
@return [ true, false ] True if validation passed, false if not.
# File lib/mongoid/persistence.rb, line 184 def update_attributes(attributes = {}, options = {}) assign_attributes(attributes, options); save end
Update the document attributes in the database and raise an error if validation failed.
@example Update the document's attributes.
document.update_attributes(:title => "Sir")
@param [ Hash ] attributes The attributes to update.
@raise [ Errors::Validations ] If validation failed.
@return [ true, false ] True if validation passed.
# File lib/mongoid/persistence.rb, line 199 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
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.
@example Upsert the document.
document.upsert
@param [ Hash ] options The validation options.
@return [ true ] True.
@since 3.0.0
# File lib/mongoid/persistence.rb, line 220 def upsert(options = {}) Operations.upsert(self, options).persist end