diff --git a/source/add-existing.txt b/source/add-existing.txt new file mode 100644 index 00000000..ae75633a --- /dev/null +++ b/source/add-existing.txt @@ -0,0 +1,229 @@ +.. _mongoid-add-to-existing: + +====================================== +Add {+odm+} to an Existing Application +====================================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: ruby framework, odm, migrate + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to add {+odm+} to an existing Sinatra +or Ruby on Rails (Rails) application. To learn how to set up a new +application that uses {+odm+}, see one of the following guides: + +- :ref:`mongoid-quick-start-rails` +- :ref:`mongoid-quick-start-sinatra` + +Sinatra Application +------------------- + +To start using {+odm+} in an existing Sinatra application, perform +the following steps: + +1. Add the ``mongoid`` dependency to your application's ``Gemfile``. + +#. Create a ``config/mongoid.yml`` configuration file and specify your + connection target, as shown in the + :ref:`mongoid-quick-start-sinatra-connect-to-mongodb` step of the + Quick Start guide. + +#. Create an application file and load your configuration file, as shown + in the :ref:`mongoid-quick-start-sinatra-view-data` step of the Quick + Start guide. + +#. Create {+odm+} models to interact with your data. + +Rails Application +----------------- + +You can add {+odm+} 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 {+odm+} 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``: + +.. code-block:: ruby + :caption: Gemfile + + gem 'mongoid' + +To use {+odm+} 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: + +.. code-block:: sh + + bundle install + +{+odm+} Configuration +~~~~~~~~~~~~~~~~~~~~~ + +Generate the default {+odm+} configuration by running the following +command: + +.. code-block:: sh + + 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: + +.. code-block:: ruby + :caption: 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 {+odm+}. + +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 {+odm+}, you must adjust your +application's existing models. + +Active Record models derive from the ``ApplicationRecord`` class and do +not have column definitions, while {+odm+} models generally have no +superclass but must include the ``Mongoid::Document`` attribute. + +When creating {+odm+} models, you can define fields in the following +ways: + +- Define fields explicitly +- Use :ref:`dynamic fields ` + +For example, a basic Active Record ``Post`` model might resemble the +following: + +.. code-block:: ruby + :caption: app/models/post.rb + + class Post < ApplicationRecord + has_many :comments, dependent: :destroy + end + +A similar {+odm+} ``Post`` model might resemble the following: + +.. code-block:: ruby + :caption: 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: + +.. code-block:: ruby + :caption: app/models/post.rb + + 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 {+odm+} supports a superset of Active Record associations, +model references are stored differently in collections when using +{+odm+} 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 + +- :website:`Modernize your apps with MongoDB Atlas + ` on the MongoDB website + +Rails API +~~~~~~~~~ + +The process for creating a Rails API application that uses {+odm+} 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 +{+odm+} follows the same process described in the preceding sections. diff --git a/source/index.txt b/source/index.txt index 87086789..01d41313 100644 --- a/source/index.txt +++ b/source/index.txt @@ -14,13 +14,14 @@ MongoDB in Ruby. To work with {+odm+} from the command line using /quick-start-rails /quick-start-sinatra + /add-existing /interact-data installation-configuration tutorials schema-configuration working-with-data API - release-notes - contributing - additional-resources - ecosystem + /release-notes + /contributing + /additional-resources + /ecosystem diff --git a/source/quick-start-rails.txt b/source/quick-start-rails.txt index c69b8418..8f3dc972 100644 --- a/source/quick-start-rails.txt +++ b/source/quick-start-rails.txt @@ -1,7 +1,7 @@ .. _mongoid-quick-start-rails: =========================== -Quick Start (Ruby on Rails) +Quick Start - Ruby on Rails =========================== .. facet:: @@ -25,6 +25,9 @@ web application, connect to a MongoDB cluster hosted on MongoDB Atlas, and perform read and write operations on the data in your cluster. +To learn how to integrate {+odm+} into an existing application, see the +:ref:`mongoid-add-to-existing` guide. + .. tip:: If you prefer to connect to MongoDB by using the {+ruby-driver+} without @@ -38,7 +41,7 @@ create flexible data models. Ruby on Rails is a web application framework for {+language+}. Rails applications use a model-view-controller (MVC) architecture that allows you to easily control how your data is -modeled and displayed. {+odm+} replaces the default ``ActiveRecord`` +modeled and displayed. {+odm+} replaces the default Active Record adapter for data modeling in Rails. To learn more about Ruby on Rails, see the `Getting Started diff --git a/source/quick-start-rails/download-and-install.txt b/source/quick-start-rails/download-and-install.txt index 88fa652d..9814fdbc 100644 --- a/source/quick-start-rails/download-and-install.txt +++ b/source/quick-start-rails/download-and-install.txt @@ -63,9 +63,8 @@ gems to your web application. cd {+quickstart-rails-app-name+} The ``--skip-active-record`` flag instructs Rails to not add - ``ActiveRecord`` as a dependency. You don't need this - dependency because you will use {+odm+} - instead. + Active Record as a dependency. You don't need this + dependency because you will use {+odm+} instead. .. tip:: MacOS Installation Issue diff --git a/source/quick-start-sinatra.txt b/source/quick-start-sinatra.txt index 9631447e..e0e053fd 100644 --- a/source/quick-start-sinatra.txt +++ b/source/quick-start-sinatra.txt @@ -1,7 +1,7 @@ .. _mongoid-quick-start-sinatra: ===================== -Quick Start (Sinatra) +Quick Start - Sinatra ===================== .. facet:: @@ -24,6 +24,9 @@ This guide shows you how to use {+odm+} in a new Sinatra web application, connect to a MongoDB cluster hosted on MongoDB Atlas, and perform read and write operations on the data in your cluster. +To learn how to integrate {+odm+} into an existing application, see the +:ref:`mongoid-add-to-existing` guide. + .. tip:: If you prefer to connect to MongoDB by using the {+ruby-driver+} without diff --git a/source/reference/compatibility.txt b/source/reference/compatibility.txt index 659fae45..7dd2ae19 100644 --- a/source/reference/compatibility.txt +++ b/source/reference/compatibility.txt @@ -481,7 +481,7 @@ Mongoid is used as a drop-in replacement. ``ActionCable``, however any existing adapter (such as `Redis `_) can be used successfully in conjunction with Mongoid models -.. [#rails-activerecord-dependency] Depends directly on ``ActiveRecord`` +.. [#rails-activerecord-dependency] Depends directly on ActiveRecord .. [#rails-activemodel-dependency] ``Mongoid::Document`` includes ``ActiveModel::Model`` and leverages ``ActiveModel::Validations`` for validations diff --git a/source/reference/crud.txt b/source/reference/crud.txt index ff70fa6f..33d2b077 100644 --- a/source/reference/crud.txt +++ b/source/reference/crud.txt @@ -707,7 +707,7 @@ each declared field: # => "Artem" To use this mechanism, each field must be explicitly declared, or the -model class must enable :ref:`dynamic fields `. +model class must enable :ref:`dynamic fields `. Custom Getters & Setters diff --git a/source/reference/fields.txt b/source/reference/fields.txt index 5e29bfee..e53ce131 100644 --- a/source/reference/fields.txt +++ b/source/reference/fields.txt @@ -1251,8 +1251,7 @@ Then, use it your model class: Note that the handler function will be invoked whenever the option is used in the field definition, even if the option's value is false or nil. - -.. _dynamic-fields: +.. _mongoid-dynamic-fields: Dynamic Fields ============== diff --git a/source/tutorials/getting-started-rails6.txt b/source/tutorials/getting-started-rails6.txt index 719c73ba..0b5e32bd 100644 --- a/source/tutorials/getting-started-rails6.txt +++ b/source/tutorials/getting-started-rails6.txt @@ -481,7 +481,7 @@ 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 :ref:`dynamic fields ` may also be used instead of +(but :ref:`dynamic fields ` may also be used instead of explicit field definitions). For example, a bare-bones Post model may look like this in ActiveRecord: diff --git a/source/tutorials/getting-started-rails7.txt b/source/tutorials/getting-started-rails7.txt index b413e159..9e7c282d 100644 --- a/source/tutorials/getting-started-rails7.txt +++ b/source/tutorials/getting-started-rails7.txt @@ -400,7 +400,7 @@ 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 :ref:`dynamic fields ` may also be used instead of +(but :ref:`dynamic fields ` may also be used instead of explicit field definitions). For example, a bare-bones Post model may look like this in ActiveRecord: