Merge remote-tracking branch 'upstream/standardization' into DOCSP-45200-change-streams

Author: norareidy

source/connect.txt

@@ -22,4 +22,6 @@ Connect to MongoDB
    :titlesonly:
    :maxdepth: 1
 
-   /connect/mongoclient
+   Create a Client </connect/mongoclient>
+   Stable API </connect/stable-api>
+   Choose a Connection Target </connect/connection-targets>

source/connect/connection-targets.txt

@@ -0,0 +1,131 @@
+.. _ruby-connection-targets:
+
+==========================
+Choose a Connection Target
+==========================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connection string, URI, server, settings, client
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use a connection string and a ``Mongo::Client`` object
+to connect to different types of MongoDB deployments.
+
+Atlas
+-----
+
+To connect to a MongoDB deployment on Atlas, include the following elements
+in your connection string:
+
+- The URL of your Atlas cluster
+- Your MongoDB username
+- Your MongoDB password
+
+Then, pass your connection string to the ``Mongo::Client`` constructor.
+
+.. tip::
+
+   Follow the :atlas:`Atlas driver connection guide </driver-connection>`
+   to retrieve your connection string.
+
+When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
+breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
+To learn more about the {+stable-api+} feature, see the :ref:`<ruby-stable-api>`
+guide.
+
+The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The
+code also uses the ``server_api`` field to specify a {+stable-api+} version.
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-connection-target-atlas
+   :end-before: end-connection-target-atlas
+   :dedent:
+
+Local Deployments
+-----------------
+
+To connect to a local standalone MongoDB deployment, specify the host of the 
+server. Optionally, specify the port of the server and the database to connect
+to. If no port is specified, the default port is ``27017``. If no database name 
+is specified, the client will use the ``admin`` database:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-local-connection
+   :end-before: end-local-connection
+   :dedent:
+
+You can also specify the host, port, and database to connect to using a  
+connection string:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-local-connection-uri
+   :end-before: end-local-connection-uri
+   :dedent:
+
+You can also specify your host as ``localhost``. The following code example 
+connects to ``localhost`` on the default port, ``27017``:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-localhost
+   :end-before: end-localhost
+   :dedent:
+
+Replica Sets
+------------
+
+To connect to a replica set, it is recommended to specify all nodes that are 
+part of the replica set. In the event that one or more nodes becomes unavailable,
+specifying all nodes allows the driver to still connect to the replica set, 
+as long as one node is available.
+
+However, it is sufficient to pass the address of any one node in the replica set 
+to the driver. The node does not have to be the primary, and it may be a hidden node. 
+The driver will then automatically discover the remaining nodes.
+
+The following example shows how to specify three members of the replica set:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-replica-set
+   :end-before: end-replica-set
+   :dedent:
+
+The following example shows how to connect to the replica set using a connection
+string:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-replica-set-uri
+   :end-before: end-replica-set-uri
+   :dedent:
+
+The following example shows how to verify the replica set name upon connection
+by using the ``replica_set`` option or the ``replicaSet`` connection string option:
+
+.. literalinclude:: /includes/connect/connection-targets.rb
+   :language: ruby
+   :start-after: start-replica-set-option
+   :end-before: end-replica-set-option
+   :dedent:
+
+API Documentation
+-----------------
+
+To learn more about creating a ``Mongo::Client`` object with the {+driver-short+},
+see the API documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ .

source/connect/stable-api.txt

@@ -0,0 +1,116 @@
+.. _ruby-stable-api:
+
+===========
+Stable API
+===========
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: compatible, backwards, upgrade
+
+.. note::
+
+   The Stable API feature requires {+mdb-server+} 5.0 or later.
+
+Overview
+--------
+
+In this guide, you can learn how to specify **{+stable-api+}** compatibility when 
+connecting to a MongoDB deployment.
+
+The {+stable-api+} feature forces the server to run operations with behaviors compatible 
+with the API version you specify. Using the {+stable-api+} ensures consistent responses 
+from the server and provides long-term API stability for your application.
+
+The following sections describe how you can enable and customize the {+stable-api+} for
+your MongoDB client. For more information about the {+stable-api+}, including a list of 
+the commands it supports, see :manual:`Stable API </reference/stable-api/>` in the
+{+mdb-server+} manual.
+
+Enable the {+stable-api+}
+-------------------------
+
+To enable the {+stable-api+}, pass a hash that specifies the {+stable-api+} version to the optional
+``server_api`` parameter when you create a ``Mongo::Client`` instance.
+
+The following code example shows how to specify {+stable-api+} version 1:
+
+.. code-block:: ruby
+
+   client = Mongo::Client.new(uri, server_api: { version: '1' })
+
+Once you create a ``Client`` instance with
+a specified API version, all commands that you run with the client use the specified
+version. If you must run commands using more than one version of the 
+{+stable-api+}, create a new ``Client``.
+
+Configure the {+stable-api+}
+----------------------------
+
+The following table describes {+stable-api+} options that you can set by specifying
+them in the ``server_api`` hash. You can use these options to customize the behavior of the
+{+stable-api+}.
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 25,75
+
+   * - Option Name
+     - Description
+
+   * - strict
+     - | **Optional**. When ``true``, if you call a command that isn't part of 
+         the declared API version, the driver raises an exception.
+       |
+       | Default: **false**
+
+   * -  deprecation_errors
+     - | **Optional**. When ``true``, if you call a command that is deprecated in the 
+         declared API version, the driver raises an exception.
+       |
+       | Default: **false**
+
+The following code example shows how you can set the two options on a ``ServerApi`` instance:
+
+.. code-block:: ruby
+
+   client = Mongo::Client.new(uri, 
+              server_api: { version: '1', strict: true, deprecation_errors: true })
+
+Troubleshooting
+---------------
+
+The following sections describe common issues you might encounter when using the {+stable-api+}.
+
+Unrecognized field 'apiVersion' on server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} raises this exception if you specify an API version and connect to a
+MongoDB server that doesn't support the {+stable-api+}. Ensure you're connecting to a
+deployment running {+mdb-server+} v5.0 or later.
+
+Provided apiStrict:true, but the command count is not in API Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} raises this exception if your ``Client`` runs an operation that
+isn't in the {+stable-api+} version you specified. To avoid this error, use an alternative
+operation supported by the specified {+stable-api+} version, or set the ``strict``
+option to ``false`` when constructing your ``ServerApi`` object.
+
+API Documentation
+-----------------
+
+For more information about using the {+stable-api+} with the {+driver-short+}, see the 
+following API documentation: 
+
+- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__

source/data-formats.txt

@@ -0,0 +1,34 @@
+.. _ruby-data-formats:
+
+============
+Data Formats
+============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :description: Learn how to use indexes by using the MongoDB Ruby Driver.
+   :keywords: ruby, query, collections, time series
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   Time Series Data </data-formats/time-series>
+
+Overview
+--------
+
+You can use several types of specialized data formats in your {+driver-short+}
+application. To learn how to work with these data formats, see the following
+sections:
+
+- :ref:`ruby-time-series`: Learn how to create a time series collection and interact with time series data.