From ffe73d3db21bb35277b08643099b3a5e7ba6e424 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 21 Jan 2025 15:26:26 -0500 Subject: [PATCH 1/3] wip --- source/index.txt | 1 + source/rails-integration.txt | 106 +++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 source/rails-integration.txt diff --git a/source/index.txt b/source/index.txt index b3cd453..0d0e4ef 100644 --- a/source/index.txt +++ b/source/index.txt @@ -19,6 +19,7 @@ MongoDB in Ruby. To work with {+odm+} from the command line using Model Your Data Configuration /working-with-data + Rails Integration API Documentation What's New Compatibility diff --git a/source/rails-integration.txt b/source/rails-integration.txt new file mode 100644 index 0000000..b284d5e --- /dev/null +++ b/source/rails-integration.txt @@ -0,0 +1,106 @@ +.. _mongoid-rails-integration: + +================= +Rails Integration +================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: web framework, api + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn about features that are automatically +enabled when you use {+odm+} in a {+ror+} application. This guide also +describes Rails-related functionality that you can enable in your application. + +Configuration +------------- + +You can set Mongoid configuration options in your ``application.rb`` along with +other Rails environment specific options by accessing config.mongoid. The +``mongoid:config`` generator will create an initializer in +``config/initializers/mongoid.rb`` which can also be used for configuring +Mongoid. Note, though, that options set in your ``config/mongoid.yml`` will +take precedence over options set elsewhere; it is recommended that whenever +possible you use ``mongoid.yml`` as the default location for Mongoid +configuration. + +.. code-block:: ruby + + module MyApplication + class Application < Rails::Application + config.mongoid.logger = Logger.new(STDERR, :warn) + end + end + + +Model Preloading +================ + +In order to properly set up single collection inheritance, Mongoid needs to preload all +models before every request in development mode. This can get slow, so if you are not +using any inheritance it is recommended you turn this feature off. + +.. code-block:: ruby + + config.mongoid.preload_models = false + + +Exceptions +========== + +Similarly to ActiveRecord, Mongoid configures Rails to automatically convert +certain exceptions to well-known HTTP status codes, as follows: + +.. code-block:: ruby + + Mongoid::Errors::DocumentNotFound : 404 + Mongoid::Errors::Validations : 422 + + +Controller Runtime Instrumentation +================================== + +Mongoid provides time spent executing MongoDB commands (obtained via a +driver command monitoring subscription) to Rails' instrumentation event +``process_action.action_controller``. This time is logged together with view +time like so: + +.. code-block:: none + + Completed 200 OK in 2739ms (Views: 12.6ms | MongoDB: 0.2ms) + +This logging is set up automatically. + +Note: the time indicated is the time taken by MongoDB cluster to execute +MongoDB operations, plus the time taken to send commands and receive +results from MongoDB over the network. It does not include time taken by +the driver and Mongoid to generate the queries or type cast and otherwise +process the results. + +Rake Tasks +========== + +Mongoid provides the following rake tasks when used in a Rails environment: + +- ``db:create``: Exists only for dependency purposes, does not actually do anything. +- ``db:create_indexes``: Reads all index definitions from the models and attempts to create them in the database. +- ``db:remove_indexes``: Reads all secondary index definitions from the models. +- ``db:drop``: Drops all collections in the database with the exception of the system collections. +- ``db:migrate``: Exists only for dependency purposes, does not actually do anything. +- ``db:purge``: Deletes all data, including indexes, from the database. Since 3.1.0 +- ``db:schema:load``: Exists only for framework dependency purposes, does not actually do anything. +- ``db:seed``: Seeds the database from db/seeds.rb +- ``db:setup``: Creates indexes and seeds the database. +- ``db:test:prepare``: Exists only for framework dependency purposes, does not actually do anything. From 2f171a86cc34b9e8e754a8329171c8de828bd7fc Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 21 Jan 2025 16:18:55 -0500 Subject: [PATCH 2/3] DOCSP-46555: rails integration --- source/add-existing.txt | 2 + source/rails-integration.txt | 138 +++++++++++++++++++++-------------- 2 files changed, 86 insertions(+), 54 deletions(-) diff --git a/source/add-existing.txt b/source/add-existing.txt index 6fa94c9..21c5c15 100644 --- a/source/add-existing.txt +++ b/source/add-existing.txt @@ -46,6 +46,8 @@ the following steps: #. Create {+odm+} models to interact with your data. +.. _mongoid-add-existing-rails: + Rails Application ----------------- diff --git a/source/rails-integration.txt b/source/rails-integration.txt index b284d5e..fc467f0 100644 --- a/source/rails-integration.txt +++ b/source/rails-integration.txt @@ -9,7 +9,7 @@ Rails Integration :values: reference .. meta:: - :keywords: web framework, api + :keywords: web framework, api, code example, ruby .. contents:: On this page :local: @@ -27,80 +27,110 @@ describes Rails-related functionality that you can enable in your application. Configuration ------------- -You can set Mongoid configuration options in your ``application.rb`` along with -other Rails environment specific options by accessing config.mongoid. The -``mongoid:config`` generator will create an initializer in -``config/initializers/mongoid.rb`` which can also be used for configuring -Mongoid. Note, though, that options set in your ``config/mongoid.yml`` will -take precedence over options set elsewhere; it is recommended that whenever -possible you use ``mongoid.yml`` as the default location for Mongoid -configuration. +You can configure {+odm+}-specific options and other Rails-environment +specific options in your main application file by accessing +``config.mongoid``. The ``mongoid:config`` generator creates an +initializer in the ``config/initializers/mongoid.rb`` file. + +.. note:: + + Any options set in your ``config/mongoid.yml`` file + take precedence over options set elsewhere. For this reason, use + ``mongoid.yml`` as the default location for {+odm+} configuration + when possible. + +.. TODO To learn more about available configuration options, + see the :ref:`` section. + +The following code demonstrates how to create a Rails logger by +accessing ``config.mongoid``: .. code-block:: ruby - module MyApplication - class Application < Rails::Application - config.mongoid.logger = Logger.new(STDERR, :warn) - end - end + module MyApplication + class Application < Rails::Application + config.mongoid.logger = Logger.new(STDERR, :warn) + end + end +.. TODO To learn more about logging settings, see the :ref:`` guide. Model Preloading -================ +---------------- -In order to properly set up single collection inheritance, Mongoid needs to preload all -models before every request in development mode. This can get slow, so if you are not -using any inheritance it is recommended you turn this feature off. +To set up single collection inheritance, {+odm+} must preload all +models before every request in development mode. This can slow down your +application, so if you are not using any inheritance you can turn this +feature off. -.. code-block:: ruby +The following code demonstrates how you can set the ``preload_models`` +feature to off by accessing ``config.mongoid``: - config.mongoid.preload_models = false +.. code-block:: ruby + config.mongoid.preload_models = false Exceptions -========== +---------- -Similarly to ActiveRecord, Mongoid configures Rails to automatically convert -certain exceptions to well-known HTTP status codes, as follows: - -.. code-block:: ruby - - Mongoid::Errors::DocumentNotFound : 404 - Mongoid::Errors::Validations : 422 +Similar to Active Record, {+odm+} configures Rails to automatically +convert certain exceptions to HTTP status codes. The following list +provides the conversions between {+odm+} exceptions and HTTP codes: +- ``Mongoid::Errors::DocumentNotFound``: Converted to ``404 Not Found`` +- ``Mongoid::Errors::Validations``: Converted to ``422 Unprocessable Content`` Controller Runtime Instrumentation -================================== +---------------------------------- -Mongoid provides time spent executing MongoDB commands (obtained via a -driver command monitoring subscription) to Rails' instrumentation event -``process_action.action_controller``. This time is logged together with view -time like so: +{+odm+} can output the time spent executing database commands to the Rails +instrumentation event ``process_action.action_controller``. {+odm+} +obtains these values through driver command monitoring. You application +logs this time amount with view time as shown in the following output: .. code-block:: none - Completed 200 OK in 2739ms (Views: 12.6ms | MongoDB: 0.2ms) + Completed 200 OK in 2739ms (Views: 12.6ms | MongoDB: 0.2ms) + +This logging is set up automatically in your Rails application. -This logging is set up automatically. +.. note:: Time Calculation -Note: the time indicated is the time taken by MongoDB cluster to execute -MongoDB operations, plus the time taken to send commands and receive -results from MongoDB over the network. It does not include time taken by -the driver and Mongoid to generate the queries or type cast and otherwise -process the results. + The time indicated in log entries is the time that the MongoDB + deployment takes to run MongoDB operations in addition to the time taken to + send commands and receive results from the MongoDB Server. It does + not include time taken by the driver and {+odm+} to generate the + queries, cast types, or otherwise process the results. Rake Tasks -========== - -Mongoid provides the following rake tasks when used in a Rails environment: - -- ``db:create``: Exists only for dependency purposes, does not actually do anything. -- ``db:create_indexes``: Reads all index definitions from the models and attempts to create them in the database. -- ``db:remove_indexes``: Reads all secondary index definitions from the models. -- ``db:drop``: Drops all collections in the database with the exception of the system collections. -- ``db:migrate``: Exists only for dependency purposes, does not actually do anything. -- ``db:purge``: Deletes all data, including indexes, from the database. Since 3.1.0 -- ``db:schema:load``: Exists only for framework dependency purposes, does not actually do anything. -- ``db:seed``: Seeds the database from db/seeds.rb -- ``db:setup``: Creates indexes and seeds the database. -- ``db:test:prepare``: Exists only for framework dependency purposes, does not actually do anything. +---------- + +You can use following rake tasks for {+odm+} when using the Rails +framework: + +- ``db:create_indexes``: Reads all index definitions from the models and + attempts to create them in the database +- ``db:remove_indexes``: Removes indexes for each model +- ``db:drop``: Drops all collections in the database except for system + collections +- ``db:purge``: Deletes all data, including indexes, from the database +- ``db:seed``: Seeds the database from the ``db/seeds.rb`` file +- ``db:setup``: Creates indexes and seeds the database + +The following rake tasks exist only for framework dependency purposes +and do not perform any actions: + +- ``db:test:prepare`` +- ``db:schema:load`` +- ``db:create`` +- ``db:migrate`` + +Additional Information +---------------------- + +To learn about how to set up a new Rails application that uses {+odm+}, +see the :ref:`mongoid-quick-start-rails` guide. + +To learn how to add {+odm+} to an existing Rails application, see the +:ref:`mongoid-add-existing-rails` section of the Add {+odm+} to an +Existing Application guide. From bac51b8847d669c323f4bcd8ee9154abd3418754 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 22 Jan 2025 12:00:44 -0500 Subject: [PATCH 3/3] RM PR fixes 1 --- source/index.txt | 5 +- source/integrations-tools.txt | 21 ++++ .../{ => integrations-tools}/add-existing.txt | 0 .../rails-integration.txt | 8 +- source/legacy-files/rails-integration.txt | 100 ------------------ 5 files changed, 27 insertions(+), 107 deletions(-) create mode 100644 source/integrations-tools.txt rename source/{ => integrations-tools}/add-existing.txt (100%) rename source/{ => integrations-tools}/rails-integration.txt (95%) delete mode 100644 source/legacy-files/rails-integration.txt diff --git a/source/index.txt b/source/index.txt index 8345ab5..4a4cfe6 100644 --- a/source/index.txt +++ b/source/index.txt @@ -14,15 +14,14 @@ MongoDB in Ruby. To work with {+odm+} from the command line using Quick Start - {+ror+} Quick Start - Sinatra - Add {+odm+} to an Existing Application Configuration Interact with Data Model Your Data Secure Your Data - Rails Integration + Integrations & Tools API Documentation What's New Compatibility Issues & Help /additional-resources - /ecosystem \ No newline at end of file + /ecosystem diff --git a/source/integrations-tools.txt b/source/integrations-tools.txt new file mode 100644 index 0000000..6def4a4 --- /dev/null +++ b/source/integrations-tools.txt @@ -0,0 +1,21 @@ +.. _mongoid-integrations-tools: + +==================== +Integrations & Tools +==================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: ruby framework, odm, rails, sinatra, ecosystem + +.. toctree:: + :caption: Integrations & Tools + + Add {+odm+} to an Existing Application + Rails Integration + +.. TODO +.. External Libraries diff --git a/source/add-existing.txt b/source/integrations-tools/add-existing.txt similarity index 100% rename from source/add-existing.txt rename to source/integrations-tools/add-existing.txt diff --git a/source/rails-integration.txt b/source/integrations-tools/rails-integration.txt similarity index 95% rename from source/rails-integration.txt rename to source/integrations-tools/rails-integration.txt index fc467f0..ff70362 100644 --- a/source/rails-integration.txt +++ b/source/integrations-tools/rails-integration.txt @@ -63,8 +63,8 @@ models before every request in development mode. This can slow down your application, so if you are not using any inheritance you can turn this feature off. -The following code demonstrates how you can set the ``preload_models`` -feature to off by accessing ``config.mongoid``: +The following code demonstrates how you can turn off preloading by +setting the ``preload_models`` feature to ``false``: .. code-block:: ruby @@ -80,8 +80,8 @@ provides the conversions between {+odm+} exceptions and HTTP codes: - ``Mongoid::Errors::DocumentNotFound``: Converted to ``404 Not Found`` - ``Mongoid::Errors::Validations``: Converted to ``422 Unprocessable Content`` -Controller Runtime Instrumentation ----------------------------------- +Execution Time Logging +---------------------- {+odm+} can output the time spent executing database commands to the Rails instrumentation event ``process_action.action_controller``. {+odm+} diff --git a/source/legacy-files/rails-integration.txt b/source/legacy-files/rails-integration.txt deleted file mode 100644 index 15ea483..0000000 --- a/source/legacy-files/rails-integration.txt +++ /dev/null @@ -1,100 +0,0 @@ -.. _rails-integration: - -***************** -Rails Integration -***************** - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Mongoid seamlessly integrates into {+ror+} applications. -This page describes features that are automatically enabled in the context -of a Rails application and Rails-related functionality which can be -manually enabled. - - -Configuration -============= - -You can set Mongoid configuration options in your ``application.rb`` along with -other Rails environment specific options by accessing config.mongoid. The -``mongoid:config`` generator will create an initializer in -``config/initializers/mongoid.rb`` which can also be used for configuring -Mongoid. Note, though, that options set in your ``config/mongoid.yml`` will -take precedence over options set elsewhere; it is recommended that whenever -possible you use ``mongoid.yml`` as the default location for Mongoid -configuration. - -.. code-block:: ruby - - module MyApplication - class Application < Rails::Application - config.mongoid.logger = Logger.new(STDERR, :warn) - end - end - - -Model Preloading -================ - -In order to properly set up single collection inheritance, Mongoid needs to preload all -models before every request in development mode. This can get slow, so if you are not -using any inheritance it is recommended you turn this feature off. - -.. code-block:: ruby - - config.mongoid.preload_models = false - - -Exceptions -========== - -Similarly to ActiveRecord, Mongoid configures Rails to automatically convert -certain exceptions to well-known HTTP status codes, as follows: - -.. code-block:: ruby - - Mongoid::Errors::DocumentNotFound : 404 - Mongoid::Errors::Validations : 422 - - -Controller Runtime Instrumentation -================================== - -Mongoid provides time spent executing MongoDB commands (obtained via a -driver command monitoring subscription) to Rails' instrumentation event -``process_action.action_controller``. This time is logged together with view -time like so: - -.. code-block:: none - - Completed 200 OK in 2739ms (Views: 12.6ms | MongoDB: 0.2ms) - -This logging is set up automatically. - -Note: the time indicated is the time taken by MongoDB cluster to execute -MongoDB operations, plus the time taken to send commands and receive -results from MongoDB over the network. It does not include time taken by -the driver and Mongoid to generate the queries or type cast and otherwise -process the results. - -Rake Tasks -========== - -Mongoid provides the following rake tasks when used in a Rails environment: - -- ``db:create``: Exists only for dependency purposes, does not actually do anything. -- ``db:create_indexes``: Reads all index definitions from the models and attempts to create them in the database. -- ``db:remove_indexes``: Reads all secondary index definitions from the models. -- ``db:drop``: Drops all collections in the database with the exception of the system collections. -- ``db:migrate``: Exists only for dependency purposes, does not actually do anything. -- ``db:purge``: Deletes all data, including indexes, from the database. Since 3.1.0 -- ``db:schema:load``: Exists only for framework dependency purposes, does not actually do anything. -- ``db:seed``: Seeds the database from db/seeds.rb -- ``db:setup``: Creates indexes and seeds the database. -- ``db:test:prepare``: Exists only for framework dependency purposes, does not actually do anything.