configuration

Mongoid configuration can be done through a mongoid.yml that specifies your options and database connections. The simplest configuration is as follows, which uses default options and connects to a single local master db on port 27017:

host: localhost
database: godfather

Note, this configuration will NOT work inside rails.

rails applications

You can generate a config file by executing the generator and then editing myapp/config/mongoid.yml to your heart's desire. Mongoid will then handle everything else from there.

$ rails g mongoid:config

This will create a configuration file with the Rails specific environment sections that that looks like this:

development:
  host: localhost
  database: godfather_development

test:
  host: localhost
  database: godfather_test

# set these environment variables on your prod server
production:
  host: <%= ENV['MONGOID_HOST'] %>
  port: <%= ENV['MONGOID_PORT'] %>
  username: <%= ENV['MONGOID_USERNAME'] %>
  password: <%= ENV['MONGOID_PASSWORD'] %>
  database: <%= ENV['MONGOID_DATABASE'] %>
  # slaves:
  #   - host: slave1.local
  #     port: 27018
  #   - host: slave2.local
  #     port: 27019

Now that you have a mongoid.yml you can't wait to delete that pesky database.yml, right? Do it and you'll start getting ActiveRecord errors all over the place. You don't need ActiveRecord unless you're trying to use Mongo in concert with a SQL database. Here's how you remove ActiveRecord from the most recent version of Rails 3...

Open myapp/config/application.rb and near the top, remove the line require 'rails/all' and add the following three lines so you end up with this:

require "action_controller/railtie"
require "action_mailer/railtie"
require "active_resource/railtie"
require "rails/test_unit/railtie"
# require "sprockets/railtie" # Uncomment this line for Rails 3.1+

sinatra, padrino, and others

You can create your mongoid.yml and place it anywhere you like. Just be sure that on application initialization you do the following:

Mongoid.load!("path/to/your/mongoid.yml")

If you want to configure Mongoid programatically, this is possible as well.

Mongoid.configure do |config|
  config.master = Mongo::Connection.new.db("godfather")
end

configuration options

Mongoid currently supports the following configuration options, either provided in the mongoid.yml or programatically (defaults in parenthesis).

  • allow_dynamic_fields (true): When attributes are not defined as fields but added to an object, they will get fields added for them dynamically and will get persisted. If set to false an error will get raised when attempting to set a value that has no field defined.
  • autocreate_indexes (false): When set to true Mongoid will attempt to create indexes each time a class is loaded. This is not recommended for any environment other than development or test.
  • identity_map_enabled (false): When set to true Mongoid will store documents loaded from the database in the identity map by their ids, so subsequent database queries for the same document in the same unit of work do not hit the database. This is only for relation queries at the moment. See the identity map documentation for more info.
  • include_root_in_json (false): When set to true mongoid will include the name of the root document and the name of each association as the root element when calling #to_json on a model.
  • max_retries_on_connection_failure (0): If you would like Mongoid to retry operations if a Mongo::ConnectionFailure occurs you may specify this option in your config. Mongoid will retry the operation every half second up to the limit that is set. This is particularly useful when using replica sets.
  • parameterize_keys (true): Tells Mongoid to convert basic special characters in composite keys to SEO friendly substrings.
  • persist_in_safe_mode (false): Tells Mongoid to perform all database operations in MongoDB's safe mode. This will cause the driver to double check operations and raise an error if they failed. Switching to true will be safe but will be a slight performance hit.
  • preload_models (false): Tells Mongoid to preload all application model classes on each request in environments where classes are not being cached. This should only be used by applications that use single collection inheritance due to performance issues with enabling this.
  • raise_not_found_error (true): Will raise a Mongoid::Errors::DocumentNotFound when attempting to find a document by an id that doesnt exist. When set to false will only return nil for the same query.
  • skip_version_check (false): If you are having issues authenticating against MongoHQ or MongoMachine because of access to the system collection being not allowed, set this to true.

Logging

You can define your own logger for Mongoid if you do not want to use the default Rails logger in your Rails' application.rb.

module MyApplication
  class Application << Rails::Application
    config.mongoid.logger = Logger.new($stdout, :warn)
  end
end

For custom logging outside of Rails, set the Mongoid logger directly.

Mongoid.logger = Logger.new($stdout)

You can turn off logging by setting the logger to nil programatically or setting the logger to false in your mongoid.yml.

logger: false