Add Mongoid to an Existing Application
On this page
Overview
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:
Sinatra Application
To start using Mongoid in an existing Sinatra application, perform the following steps:
Add the
mongoid
dependency to your application'sGemfile
.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.Create an application file and load your configuration file, as shown in the View MongoDB Data step of the Quick Start guide.
Create Mongoid models to interact with your data.
Rails Application
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.
Modify Dependencies
Add the mongoid
gem to your application's 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
Mongoid Configuration
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.
Modify Frameworks
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:
# 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.
Disable Active Record Adapters
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
.
Adjust Models
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:
Define fields explicitly
Use dynamic fields
For example, a basic Active Record Post
model might resemble the
following:
class Post < ApplicationRecord has_many :comments, dependent: :destroy end
A similar Mongoid Post
model might resemble the following:
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:
class Post include Mongoid::Document include Mongoid::Attributes::Dynamic has_many :comments, dependent: :destroy end
Data Migration
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:
RDBMS to MongoDB Migration Guide in the AWS documentation
Modernize your apps with MongoDB Atlas on the MongoDB website
Rails API
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.