mongodb/mongoid

*****************
Rails Integration
*****************

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Mongoid seamlessly integrates into Ruby on Rails applications.
This page describes features that are automatically enabled in the context
of a Rails application and Rails-related functionality which can be
manually enabled.


Configuration
=============

You can set Mongoid configuration options in your ``application.rb`` along with
other Rails environment specific options by accessing config.mongoid. The
``mongoid:config`` generator will create an initializer in
``config/initializers/mongoid.rb`` which can also be used for configuring
Mongoid. Note, though, that options set in your ``config/mongoid.yml`` will
take precedence over options set elsewhere; it is recommended that whenever
possible you use ``mongoid.yml`` as the default location for Mongoid
configuration.

.. code-block:: ruby

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


Model Preloading
================

In order to properly set up single collection inheritance, Mongoid needs to preload all
models before every request in development mode. This can get slow, so if you are not
using any inheritance it is recommended you turn this feature off.

.. code-block:: ruby

  config.mongoid.preload_models = false


Exceptions
==========

Similarly to ActiveRecord, Mongoid configures Rails to automatically convert
certain exceptions to well-known HTTP status codes, as follows:

.. code-block:: ruby

  Mongoid::Errors::DocumentNotFound : 404
  Mongoid::Errors::Validations : 422


Controller Runtime Instrumentation
==================================

Mongoid provides time spent executing MongoDB commands (obtained via a
driver command monitoring subscription) to Rails' instrumentation event
``process_action.action_controller``. This time is logged together with view
time like so:

.. code-block:: none

  Completed 200 OK in 2739ms (Views: 12.6ms | MongoDB: 0.2ms)

This logging is set up automatically.

Note: the time indicated is the time taken by MongoDB cluster to execute
MongoDB operations, plus the time taken to send commands and receive
results from MongoDB over the network. It does not include time taken by
the driver and Mongoid to generate the queries or type cast and otherwise
process the results.

Rake Tasks
==========

Mongoid provides the following rake tasks when used in a Rails environment:

- ``db:create``: Exists only for dependency purposes, does not actually do anything.
- ``db:create_indexes``: Reads all index definitions from the models and attempts to create them in the database.
- ``db:remove_indexes``: Reads all secondary index definitions from the models.
- ``db:drop``: Drops all collections in the database with the exception of the system collections.
- ``db:migrate``: Exists only for dependency purposes, does not actually do anything.
- ``db:purge``: Deletes all data, including indexes, from the database. Since 3.1.0
- ``db:schema:load``: Exists only for framework dependency purposes, does not actually do anything.
- ``db:seed``: Seeds the database from db/seeds.rb
- ``db:setup``: Creates indexes and seeds the database.
- ``db:test:prepare``: Exists only for framework dependency purposes, does not actually do anything.