DOCSP-44647: add to existing app

.github/workflows/vale-tdbx.yml

@@ -12,27 +12,30 @@ jobs:
       - name: checkout
         uses: actions/checkout@v4
 
+      - name: Install docutils
+        run: sudo apt-get install -y docutils
+
       - id: files
         uses: masesgroup/retrieve-changed-files@v2
         with:
-          format: 'csv'
+          format: "csv"
 
       - name: checkout-latest-rules
         uses: actions/checkout@v4
         with:
           repository: mongodb/mongodb-vale-action
-          path: './tdbx-vale-rules'
+          path: "./tdbx-vale-rules"
           token: ${{secrets.GITHUB_TOKEN}}
 
       - name: move-files-for-vale-action
         run: |
-            cp tdbx-vale-rules/.vale.ini .vale.ini
-            mkdir -p .github/styles/
-            cp -rf tdbx-vale-rules/.github/styles/ .github/
+          cp tdbx-vale-rules/.vale.ini .vale.ini
+          mkdir -p .github/styles/
+          cp -rf tdbx-vale-rules/.github/styles/ .github/
       - name: run-vale
         uses: errata-ai/vale-action@reviewdog
         with:
           reporter: github-pr-check
           files: ${{steps.files.outputs.added_modified}}
           fail_on_error: true
-          token: ${{secrets.GITHUB_TOKEN}}
+          token: ${{secrets.GITHUB_TOKEN}}

source/add-existing.txt

@@ -0,0 +1,232 @@
+.. _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, you can follow
+the same steps described in the
+:ref:`Sinatra Quick Start <mongoid-quick-start-sinatra>` guide.
+
+The following steps describe how to add {+odm+} to a Sinatra application:
+
+1. Add the ``mongoid`` dependency to your application's ``Gemfile``.
+
+#. Create a ``config/mongoid.yml`` configuration file and specify your
+   connection target.
+
+#. Create an application file and load your configuration file.
+
+#. Create {+odm+} models.
+
+Rails Application
+-----------------
+
+You can add {+odm+} to an existing Rails application to run alongside
+other ActiveRecord 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
+ActiveRecord, 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 such as ``sqlite`` or ``pg`` listed in the ``Gemfile``.
+
+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 it
+requires all the components of Rails by including the ``require
+'rails/all'`` specification, change this to specify individual
+frameworks.
+
+To verify the contents of ``rails/all`` for Rails 7, see the
+:github:`rails GitHub repository
+</rails/rails/blob/7-0-stable/railties/lib/rails/all.rb>`.
+
+The following code is a sample ``config/application.rb`` file that
+demonstrates how to specify individual frameworks instead of using ``rails/all``:
+
+.. 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 ActiveRecord, the `ActionText
+   <https://guides.rubyonrails.org/action_text_overview.html>`__,
+   `ActiveStorage <https://edgeguides.rubyonrails.org/active_storage_overview.html>`__ and
+   `ActionMailbox
+   <https://guides.rubyonrails.org/action_mailbox_basics.html>`__
+   adapters cannot be used alongside {+odm+}.
+
+Disable ActiveRecord
+~~~~~~~~~~~~~~~~~~~~
+
+Review your application's configuration files, such as
+``config/application.rb``, then remove or comment out any references to
+``config.active_record`` and ``config.active_storage``.
+
+Adjust Models
+~~~~~~~~~~~~~
+
+If your application already uses models, you must adjust them to
+migrate from using ActiveRecord to {+odm+}.
+
+ActiveRecord models derive from ``ApplicationRecord`` and do not have
+column definitions. {+odm+} models generally have no superclass but must
+include the ``Mongoid::Document`` attribute. {+odm+} models usually
+define fields explicitly. You can also use :ref:`dynamic fields
+<mongoid-dynamic-fields>` instead of explicit field definitions.
+
+For example, a basic ActiveRecord ``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
+
+Or, 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
+
+{+odm+} does not use ActiveRecord migrations, because MongoDB does not
+require a defined schema before you can store data.
+
+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 ActiveRecord associations,
+the way that model references are stored in collections is different between
+{+odm+} and ActiveRecord.
+
+Visit the following resources to learn more about migrating from an
+RDBMS to MongoDB:
+
+- `RDBMS to MongoDB Migration Guide
+  <https://s3.amazonaws.com/info-mongodb-com/RDBMStoMongoDBMigration.pdf>`__
+  in the AWS documentation
+
+- :website:`Modernize your apps with MongoDB Atlas
+  </solutions/use-cases/modernize>` 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.

source/index.txt

@@ -14,12 +14,13 @@
 
    /quick-start-rails
    /quick-start-sinatra
-   installation-configuration
-   tutorials
-   schema-configuration
-   working-with-data
+   /add-existing
+   /installation-configuration
+   /tutorials
+   /schema-configuration
+   /working-with-data
    API <https://mongodb.com/docs/mongoid/master/api/>
-   release-notes
-   contributing
-   additional-resources
-   ecosystem
+   /release-notes
+   /contributing
+   /additional-resources
+   /ecosystem

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 migrate an existing application to use {+odm+}, 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 ActiveRecord
 adapter for data modeling in Rails.
 
 To learn more about Ruby on Rails, see the `Getting Started

source/quick-start-rails/download-and-install.txt

@@ -63,7 +63,7 @@ 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
+      ActiveRecord as a dependency. You don't need this
       dependency because you will use {+odm+}
       instead.
 

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 migrate an existing application to use {+odm+}, see the
+:ref:`mongoid-add-to-existing` guide.
+
 .. tip::
 
    If you prefer to connect to MongoDB by using the {+ruby-driver+} without

source/reference/compatibility.txt

@@ -481,7 +481,7 @@ Mongoid is used as a drop-in replacement.
    ``ActionCable``, however any existing adapter (such as `Redis <https://guides.rubyonrails.org/action_cable_overview.html#redis-adapter>`_)
    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

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 <dynamic-fields>`.
+model class must enable :ref:`dynamic fields <mongoid-dynamic-fields>`.
 
 
 Custom Getters & Setters

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
 ==============

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 <dynamic-fields>` may also be used instead of
+(but :ref:`dynamic fields <mongoid-dynamic-fields>` may also be used instead of
 explicit field definitions).
 
 For example, a bare-bones Post model may look like this in ActiveRecord:

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 <dynamic-fields>` may also be used instead of
+(but :ref:`dynamic fields <mongoid-dynamic-fields>` may also be used instead of
 explicit field definitions).
 
 For example, a bare-bones Post model may look like this in ActiveRecord: