Persistence

Standard

Mongoid's standard persistence methods come in the form of common methods you would find in other mapping frameworks. The following table is a cheat sheet with the method in Mongoid on the left, and the Moped driver operation on the right.

Mongoid never persists the entire document at once unless it is new. It figures out what has changed, and only ever updates the changed items atomically.

Person.create(
  first_name: "Heinrich",
  last_name: "Heine"
)

Person.create([
  { first_name: "Heinrich", last_name: "Heine" },
  { first_name: "Willy", last_name: "Brandt" }
])

Person.create(first_name: "Heinrich") do |doc|
  doc.last_name = "Heine"
end

collections[:people].insert({
  first_name: "Heinrich",
  last_name: "Heine"
})
collections[:people].insert([
  { first_name: "Heinrich", last_name: "Heine" },
  { first_name: "Willy", last_name: "Brandt" }
])

Person.create!(
  first_name: "Heinrich",
  last_name: "Heine"
)

Person.create!(first_name: "Heinrich") do |doc|
  doc.last_name = "Heine"
end

collections[:people].insert({
  first_name: "Heinrich",
  last_name: "Heine"
})

person = Person.new(
  first_name: "Heinrich",
  last_name: "Heine"
)
person.save
person.save(validate: false)

person.first_name = "Christian Johan"
person.save

collections[:people].insert({
  first_name: "Heinrich",
  last_name: "Heine"
})

collections[:people].find(...).
  update("$set" => { first_name: "Christian Johan" })

person = Person.new(
  first_name: "Heinrich",
  last_name: "Heine"
)
person.save!

person.first_name = "Christian Johan"
person.save!

collections[:people].insert({
  first_name: "Heinrich",
  last_name: "Heine"
})

collections[:people].find(...).
  update("$set" => { first_name: "Christian Johan" })

person.update_attributes(
  first_name: "Jean",
  last_name: "Zorg"
)

collections[:people].find(...).
  update("$set" => {
    first_name: "Jean",
    last_name: "Zorg"
  })

person.update_attributes!(
  first_name: "Jean",
  last_name: "Zorg"
)

collections[:people].find(...).
  update("$set" => {
    first_name: "Jean",
    last_name: "Zorg"
  })

person.update_attribute(:first_name, "Jean")

collections[:people].find(...).
  update("$set" => { first_name: "Jean" })

person = Person.new(
  first_name: "Heinrich",
  last_name: "Heine"
)
person.upsert

collections[:people].upsert({
  first_name: "Heinrich",
  last_name: "Heine"
})

person.touch
person.touch(:audited_at)

collections[:people].find(...).
  update("$set" => { updated_at: Time.now })

collections[:people].find(...).
  update({
    "$set" => {
      updated_at: Time.now,
      audited_at: Time.now
    }
  })

person.delete

collections[:people].find(...).remove

person.destroy

collections[:people].find(...).remove

Person.delete_all

Person.delete_all(first_name: "Heinrich")

collections[:people].find.remove_all

collections[:people].find(first_name: "Heinrich").
  remove_all

Person.destroy_all

Person.destroy_all(first_name: "Heinrich")

collections[:people].find.remove_all

collections[:people].find(first_name: "Heinrich").
  remove_all

Atomic Persistence

Although Mongoid performs atomic operations under the covers by default, there may be cases where you want to do this explicitly without persisting other fields. Mongoid provides support for all of these operations as well.

When executing atomic operations via these methods, no callbacks will ever get run, nor will any validations.

person.add_to_set(aliases: "Bond")

collections[:people].find(...).
  update("$addToSet" => { aliases: "Bond" })

person.bit(age: { and: 10, or: 12 })

collections[:people].find(...).
  update("$bit" => { age: { and: 10, or: 12 }})

person.inc(age: 1)

collections[:people].find(...).
  update("$inc" => { age: 1 })

person.pop(aliases: 1)

collections[:people].find(...).
  update("$pop" => { aliases: 1 })

person.pull(aliases: "Bond")

collections[:people].find(...).
  update("$pull" => { aliases: "Bond" })

person.pull_all(aliases: [ "Bond", "James" ])

collections[:people].find(...).
  update("$pullAll" => { aliases: [ "Bond", "James" ]})

person.push(aliases: ["007","008"])

collections[:people].find(...).
  update("$push" => { aliases: ["007","008'] })

person.rename(bday: :dob)

collections[:people].find(...).
  update("$rename" => { "bday" => "dob" })

person.set(name: "Tyler Durden")

collections[:people].find(...).
  update("$set" => { name: "Tyler Durden" })

person.unset(:name)

collections[:people].find(...).
  update("$unset" => { name: 1 })

Custom

There may be cases where you want to persist documents to different sources from their defaults, or with different options from the default. Mongoid provides run-time support for this as well as support on a per-model basis.

Model Level Persistence Options

On a per-model basis, you can tell it to store in a custom collection name, a different database, or a different session. The following example would store the Band class by default into a collection named "artists" in the database named "music", with the session "secondary".

Note that the value supplied to the session option must be configured under sessions in your mongoid.yml.

class Band
  include Mongoid::Document
  store_in collection: "artists", database: "music", session: "secondary"
end

If no `store_in` macro would have been provided, Mongoid would store the model in a collection named "bands" in the default database in the default session.

Runtime Persistence Options

You can change at runtime where to store, query, update, or remove documents by prefixing any operation with #with.

Band.with(database: "music-non-stop").create
Band.with(collection: "artists").delete_all
band.with(session: :tertiary).save!

Persisting using with is a one time switch in the persistence context - it changes back to its defaults immediately after. Mongoid will not remember anything specific on the document level regarding how it was saved when using this method. A potential gotcha with this is persisting a document via with and then immediately updating it after.

band = Band.new(name: "Scuba")
band.with(collection: "artists").save!
band.update_attribute(likes: 1000) # This will not save - tries the collection "bands"
band.with(collection: "artists").update_attribute(likes: 1000) # This will update the document.

If you want to switch the persistence context for all operations at runtime, but don't want to be using with all over your code, Mongoid provides the ability to do this as the session and database level globally. The methods for this are Mongoid.override_session and Mongoid.override_database. A useful case for this are internationalized applications that store information for different locales in different databases or sessions, but the schema in each remains the same.

class BandsController < ApplicationController
  before_filter :switch_database
  after_filter :reset_database

  private

  def switch_database
    I18n.locale = params[:locale] || I18n.default_locale
    Mongoid.override_database("my_db_name_#{I18n.locale}")
  end

  def reset_database
    Mongoid.override_database(nil)
  end
end

In the above example, all persistence operations would be stored in the alternative database for all remaining operations on this thread. This is why the after request set the override back to nil - it ensures subsequent requests with no local params use the default option.

#withis also used for changing write mode options temporarily at runtime.

Band.with(write: { w: "majority" }).create
Band.with(write: { w: 3 }).create!

The values that can be passed with :safe are:

• true: Persist in safe mode, no extra options.
• false: Don't persist in safe mode.
• fsync: true|false: Whether to perform an fsync.
• w: n: The number of nodes to write to before returning.
• wtimeout: n: The timeout value for writing to multiple nodes.

Session and Collection Access

If you want to drop down to the driver level to perform operations, you can grab the Moped session or collection from the model or document instance.

Band.mongo_session
band.mongo_session
Band.collection
band.collection

From here you also have the same runtime persistence options using Moped's #with. The Moped documentation will go into more detail about this.

Band.mongo_session.with(write: {w: 0}, database: "musik") do |session|
  session[:artists].find(...)
end

Capped Collections

Mongoid does not provide a mechanism for creating capped collections on the fly - you will need to create these yourself one time up front either with Moped or via the Mongo console.

To create a capped collection with Moped:

session.command(create: "name", capped: true, size: 10000000, max: 1000)

To create a capped collection from the Mongo console:

db.createCollection("name", { capped: true, size: 10000000, max: 1000 });