Persistence Configuration

Model-Level Persistence Options

Suppose you want to store your model's documents in a collection with a different name than the pluralized form of the model class name. You can use the store_in macro to change the collection, database, or client where Mongoid stores a model's documents. The following example shows how to use the store_in macro to store documents from the Person class in a collection called citizens in the other database within a client named analytics:

class Person
  include Mongoid::Document
  store_in collection: "citizens", database: "other", client: "analytics"
end

The store_in macro can also accept a lambda function. This is useful if you want to define a persistence context with values that cannot use a constant string.

You might want to use this pattern in a multi-tenant application, where multiple users share common access to an application. By using a lambda, you can define a persistence context based on information that is local to the current thread so that users cannot access each others' data.

The following example stores documents in a database determined by a thread-local variable:

class Band
  include Mongoid::Document
  store_in database: ->{ Thread.current[:database] }
end

Runtime Persistence Options

You can use the with method on a model class or instance to change a model's persistence configuration for a group of operations during runtime.

Call the with method on a model class or instance and pass options that define a persistence context. You can call the with method in two ways:

• with(context, options): context is an instance of Mongoid::PersistenceContext and options is a Hash that represents a customizable set of options.

• with(options): options is a Hash that represents a customizable set of options.

Then, use a block to define the operations that you want to execute in the specified context. The context that you define only exists while the code in the block runs.

By default, Mongoid stores documents for the Band class in a collection called bands. The following code example uses the with method to temporarily use a different client, database, and collection to perform operations on the Band class's documents:

class Band
  include Mongoid::Document
  field :name, type: String
  field :likes, type: Integer
end
# Creates document in 'bands' collection in 'music-non-stop' database within
# default cluster
Band.with(database: "music-non-stop") do |band_class|
  band_class.create(name: "Medusa and the Polyps")
end
# Deletes all documents in 'artists' collection within default database
Band.with(collection: "artists") do |band_class|
  band_class.delete_all
end
band = Band.new(name: "Japanese Breakfast")
# Perform operations on tertiary cluster
band.with(client: :tertiary) do |band_object|
  band_object.save!
    
  band.save!
end

You can also pass the with method configuration options for read or write operations. The configurations apply only to the specified type of operation.

The following example uses the with method to specify the use of the secondary node for all read operations within the block.

Band.with(read: {mode: :secondary}) do
  Band.count
  # This write operation runs in the 
  # new persistence context, but is 
  # not affected by the read preference.
  Band.create(name: "Metallica")
end

class BandsController < ApplicationController
  before_action :switch_database
  after_action :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

mongo_client.with

The following code example accesses the client used by the Band model class. It then uses the with method on the client to write to the music database, setting the w write option to 0 to not require write acknowledgement.

Band.mongo_client.with(write: { w: 0 }, database: "music") do |client|
  client[:artists].find(...)
end

collection.with

You can override the :read and :write options on a collection by using the with method. The following example shows how to use the with method to set the w write option to 0:

Band.collection.with(write: { w: 0 }) do |collection|
  collection[:artists].find(...)
end