Getting Started (Rails 7)

Install rails

We will use a Rails generator to create the application skeleton. In order to do so, the first step is to install the rails gem:

gem install rails -v 7.1

Create New Application

Use the rails command to create the application skeleton, as follows:

rails new blog --skip-active-record
cd blog

We pass --skip-active-record to request that ActiveRecord is not added as a dependency, because we will be using Mongoid instead.

rails new blog --skip-active-record --skip-test --skip-system-test
cd blog

Setup Mongoid

1. Modify the Gemfile to add a reference to the mongoid gem:

  gem 'mongoid'

2. Install gem dependencies:

bundle install

3. Generate the default Mongoid configuration:

bin/rails g mongoid:config

This generator will create the config/mongoid.yml configuration file (used to configure the connection to the MongoDB deployment) and the config/initializers/mongoid.rb initializer file (which may be used for other Mongoid-related configuration). Note that as we are not using ActiveRecord we will not have a database.yml file.

development:
  clients:
    default:
      database: blog_development
      hosts:
        - localhost:27017
      options:
        server_selection_timeout: 1

development:
  clients:
    default:
      uri: mongodb+srv://user:pass@yourcluster.mongodb.net/blog_development?retryWrites=true&w=majority
      options:
        server_selection_timeout: 5

Run Application

You can now start the application server by running:

bin/rails s

Access the application by navigating to localhost:3000.

Add Posts

Using the standard Rails scaffolding, Mongoid can generate the necessary model, controller and view files for our blog so that we can quickly begin creating blog posts:

bin/rails g scaffold Post title:string body:text

Navigate to localhost:3000/posts to create posts and see the posts that have already been created.

Add Comments

To make our application more interactive, let's add the ability for users to add comments to our posts.

Create the Comment model:

bin/rails g scaffold Comment name:string message:string post:belongs_to

Open the Post model file, app/models/post.rb, and add a has_many association for the comments:

  class Post
    include Mongoid::Document
    include Mongoid::Timestamps
    field :title, type: String
    field :body, type: String
    has_many :comments, dependent: :destroy
  end

Open app/views/posts/show.html.erb and add a section rendering existing comments and prompting to leave a new comment:

<section class="section comments">
  <div class="container">
    <h2 class="subtitle is-5">
      <strong><%= @post.comments.count %></strong> Comments
    </h2>
    <%= render @post.comments %>
    <div class="comment-form">
      <hr />
      <h3 class="subtitle is-3">Leave a reply</h3>
      <%= render partial: 'comments/form', locals: { comment: @post.comments.build } %>
    </div>
  </div>
</section>

Open app/views/comments/_form.html.erb and change the type of field for :message from text_field to text_area, as well as the type of field for :post_id from text_field to hidden_field. The result should look like this:

<%= form_with(model: comment, local: true) do |form| %>
  <% if comment.errors.any? %>
    <div id="error_explanation">
      <h2><%= pluralize(comment.errors.count, "error") %> prohibited this comment from being saved:</h2>
      <ul>
        <% comment.errors.full_messages.each do |message| %>
          <li><%= message %></li>
        <% end %>
      </ul>
    </div>
  <% end %>
  <div class="field">
    <%= form.label :name %>
    <%= form.text_field :name %>
  </div>
  <div class="field">
    <%= form.label :message %>
    <%= form.text_area :message %>
  </div>
  <div class="field">
    <%= form.hidden_field :post_id %>
  </div>
  <div class="actions">
    <%= form.submit %>
  </div>
<% end %>

Next replace app/view/comments/_comment.html.erb with the following contents:

<p>
  <strong><%= comment.name %>:</strong>
  <%= comment.message %>
  <%= link_to 'Delete', [comment],
    data: {
      "turbo-method": :delete,
      "turbo-confirm": 'Are you sure?'
    } %>
</p>

You should now be able to leave comments for the posts:

Dependencies

First, the mongoid gem will need to be added your Gemfile.

  gem 'mongoid'

If Mongoid will be the only database adapter, remove or comment out any RDBMS libraries like sqlite or pg mentioned in the Gemfile.

Install gem dependencies:

bundle install

Mongoid Configuration

Generate the default Mongoid configuration:

bin/rails g mongoid:config

This generator will create the config/mongoid.yml configuration file (used to configure the connection to the MongoDB deployment) and the config/initializers/mongoid.rb initializer file (which may be used for other Mongoid-related configuration). In general, it is recommended to use mongoid.yml for all Mongoid configuration.

Review the sections Configure for Self Managed MongoDB and Configure for MongoDB Atlas to decide how you would like to deploy MongoDB, and adjust the Mongoid configuration (config/mongoid.yml) to match.

Loaded Frameworks

Examine config/application.rb. If it is requiring all components of Rails via require 'rails/all', change it to require individual frameworks. To verify the contents of rails/all for your version see the Github Repository:

# Remove or comment out
#require "rails/all"
# Add the following instead of "rails/all":
require "rails"
# 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

ActiveRecord Configuration

Review all configuration files (config/application.rb, config/environments/{development,production.test}.rb) and remove or comment out any references to config.active_record and config.active_storage.

Adjust Models

If your application already has models, these will need to be changed when migrating from ActiveRecord to Mongoid.

ActiveRecord models derive from ApplicationRecord and do not have column definitions. Mongoid models generally have no superclass but must include Mongoid::Document, and usually define the fields explicitly (but dynamic fields may also be used instead of explicit field definitions).

For example, a bare-bones Post model may look like this in ActiveRecord:

class Post < ApplicationRecord
  has_many :comments, dependent: :destroy
end

The same model may look like this in Mongoid:

class Post
  include Mongoid::Document
  field :title, type: String
  field :body, type: String
  has_many :comments, dependent: :destroy
end

Or like this with dynamic fields:

class Post
  include Mongoid::Document
  include Mongoid::Attributes::Dynamic
  has_many :comments, dependent: :destroy
end

Mongoid does not utilize ActiveRecord migrations, since MongoDB does not require a schema to be defined prior to storing data.

Data Migration

If you already have data in a relational database that you would like to transfer to MongoDB, you will need to perform a data migration. As noted above, no schema migration is necessary because MongoDB does not require a predefined schema to store the data.

The migration tools are often specific to the data being migrated because, even though Mongoid supports a superset of ActiveRecord associations, the way that model references are stored in collections differs between Mongoid and ActiveRecord. With that said, MongoDB has some resources on migrating from an RDBMS to MongoDB such as the RDBMS to MongoDB Migration Guide and Modernization Guide.

Rails API

The process for creating a Rails API application with Mongoid is the same as when creating a regular application, with the only change being the --api parameter to rails new. Migrating a Rails API application to Mongoid follows the same process described above for regular Rails applications.

A complete Rails API application similar to the one described in this tutorial can be found in the mongoid-demo GitHub repository.