Docs Menu

Add Mongoid to an Existing Application

In this guide, you can learn how to add Mongoid to an existing Sinatra or Ruby on Rails (Rails) application. To learn how to set up a new application that uses Mongoid, see one of the following guides:

To start using Mongoid in an existing Sinatra application, perform the following steps:

  1. Add the mongoid dependency to your application's Gemfile.

  2. Create a config/mongoid.yml configuration file and specify your connection target, as shown in the Configure Your MongoDB Connection step of the Quick Start guide.

  3. Create an application file and load your configuration file, as shown in the View MongoDB Data step of the Quick Start guide.

  4. Create Mongoid models to interact with your data.

You can add Mongoid to an existing Rails application to run alongside other Active Record adapters. To use a combination of adapters, you can add the mongoid dependency and populate the configuration file with your connection information to start using MongoDB in your application.

To adapt an existing Rails application to use only Mongoid instead of Active Record, you must make other configuration changes, as described in the following sections.

Add the mongoid gem to your application's Gemfile:

Gemfile
gem 'mongoid'

To use Mongoid as the only database adapter, remove or comment out any RDBMS libraries listed in the Gemfile, such as sqlite or pg.

Then, install the dependencies by running the following command:

bundle install

Generate the default Mongoid configuration by running the following command:

bin/rails g mongoid:config

This generator creates the config/mongoid.yml configuration file used to configure the connection to the MongoDB deployment and the config/initializers/mongoid.rb initializer file that you can use to set other options.

In the config/mongoid.yml file, specify your connection string and other connection options.

Open the config/application.rb file and examine the contents. If the file uses the require "rails/all" statement to load all Rails components, delete this statement. You must add a separate require statement for each Rails component, as shown in the following sample config/application.rb file:

config/application.rb
# Remove or comment out rails/all
#require "rails/all"
# Add the following instead of rails/all:
require "rails"
# Comment out unneeded frameworks
# require "active_record/railtie" rescue LoadError
# require "active_storage/engine" rescue LoadError
require "action_controller/railtie" rescue LoadError
require "action_view/railtie" rescue LoadError
require "action_mailer/railtie" rescue LoadError
require "active_job/railtie" rescue LoadError
require "action_cable/engine" rescue LoadError
# require "action_mailbox/engine" rescue LoadError
# require "action_text/engine" rescue LoadError
require "rails/test_unit/railtie" rescue LoadError

Note

Because they rely on Active Record, the ActionText, ActiveStorage, and ActionMailbox adapters cannot be used alongside Mongoid.

In config/application.rb and your application's other configuration files, remove or comment out any references to config.active_record and config.active_storage.

To migrate from using Active Record to Mongoid, you must adjust your application's existing models.

Active Record models derive from the ApplicationRecord class and do not have column definitions, while Mongoid models generally have no superclass but must include the Mongoid::Document attribute.

When creating Mongoid models, you can define fields in the following ways:

For example, a basic Active Record Post model might resemble the following:

app/models/post.rb
class Post < ApplicationRecord
has_many :comments, dependent: :destroy
end

A similar Mongoid Post model might resemble the following:

app/models/post.rb
class Post
include Mongoid::Document
field :title, type: String
field :body, type: String
has_many :comments, dependent: :destroy
end

Instead of using predefined fields, you can define the Post model by using dynamic fields, as shown in the following code:

app/models/post.rb
class Post
include Mongoid::Document
include Mongoid::Attributes::Dynamic
has_many :comments, dependent: :destroy
end

If you already have data in a relational database that you want to move into MongoDB, you must perform a data migration. You don't have to perform schema migration because MongoDB does not require a predefined schema to store the data.

Migration tools are often specific to datasets. Even though Mongoid supports a superset of Active Record associations, model references are stored differently in collections when using Mongoid compared to Active Record.

Visit the following resources to learn more about migrating from an RDBMS to MongoDB:

The process for creating a Rails API application that uses Mongoid is almost the same as for creating a normal application. The only difference is that you must add the --api flag when running rails new to create the application. Migrating a Rails API application to Mongoid follows the same process described in the preceding sections.