DOCSP-35938: Connection Guide docs

docs/fundamentals.txt

@@ -15,13 +15,15 @@ Fundamentals
    :titlesonly:
    :maxdepth: 1
 
+   /fundamentals/connection
    /fundamentals/database-collection
    /fundamentals/read-operations
    /fundamentals/write-operations
 
 Learn how to use the {+odm-long+} to perform the following tasks:
 
-- :ref:`Manage Databases and Collections <laravel-db-coll>`
+- :ref:`Connections <laravel-fundamentals-connection>`
+- :ref:`Databases and Collections <laravel-db-coll>`
 - :ref:`Read Operations <laravel-fundamentals-read-ops>`
 - :ref:`Write Operations <laravel-fundamentals-write-ops>`
 

docs/fundamentals/connection.txt

@@ -0,0 +1,25 @@
+.. _laravel-fundamentals-connection:
+
+===========
+Connections
+===========
+
+.. toctree::
+
+   /fundamentals/connection/connect-to-mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+Learn how to set up a connection and specify connection behavior from your
+Laravel application to a MongoDB deployment by using {+odm-short+} in the
+following sections:
+
+- :ref:`Connect to MongoDB <laravel-connect-to-mongodb>`
+

docs/fundamentals/connection/connect-to-mongodb.txt

@@ -0,0 +1,255 @@
+.. _laravel-connect-to-mongodb:
+
+================
+Connection Guide
+================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, seedlist, dsn, data source name
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to connect your Laravel application to a
+MongoDB instance or replica set deployment by using {+odm-short+}.
+
+This guide includes the following sections:
+
+- :ref:`Connection URI <laravel-connection-uri>`, which explains connection
+  URIs and their constituent parts
+- :ref:`Laravel Data Source Name <laravel-data-source-name>`, which explains
+  how to specify a connection to MongoDB.
+- :ref:`Connection Example <laravel-atlas-connection-example>`, which  provides
+  examples that show how to connect to MongoDB by using an Atlas connection
+  string.
+- :ref:`Other Ways to Connect to MongoDB <laravel-other-ways-to-connect>`
+  describes ways to connect to MongoDB deployments that are not hosted
+  on Atlas.
+
+.. _laravel-connection-uri:
+
+Connection URI
+--------------
+
+A **connection URI**, also known as a connection string, specifies how
+{+odm-short+} connects to MongoDB and how to behave while connected.
+
+Parts of a Connection URI
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following figure explains each part of a sample connection URI:
+
+.. figure:: /includes/figures/connection_uri_parts.png
+   :alt: Parts of a connection URI
+
+In this connection URI, ``mongodb+srv`` is the protocol, which uses the
+:manual:`DNS Seed List Connection Format </reference/connection-string/#dns-seed-list-connection-format>`
+for greater flexibility in your deployment and the ability to change the
+servers in rotation without reconfiguring clients.
+
+If the machine that hosts your MongoDB deployment does not support this
+feature, use protocol for the
+:manual:`Standard Connection String Format </reference/connection-string/#std-label-connections-standard-connection-string-format>`
+instead.
+
+If you use a password-based authentication, the part of the connection
+string after the protocol contains your username and password. Replace the
+placeholder for ``user`` with your username and ``pass`` with your password.
+If you use an authentication mechanism that does not require a username
+and password, omit this part of the connection URI.
+
+The part of the connection string after the credentials specifies your MongoDB
+instance's hostname or IP address and port. The preceding example uses
+``sample.host`` as the hostname and ``27017`` as the port. Replace these values
+to point to your MongoDB instance.
+
+The last part of the connection string specifies connection and authentication
+options. In the example, we set the following connection options and values:
+
+- ``maxPoolSize=20``
+- ``w=majority``
+
+.. _laravel-data-source-name:
+
+Laravel Data Source Name
+------------------------
+
+In Laravel, you can specify your database connection details in a connection
+string, called a **data source name (DSN)**. {+odm-short+} lets you use the
+MongoDB standard connection string format to specify the connection details
+and options.
+
+The next sections provide common ways of specifying MongoDB connections.
+
+.. _laravel-atlas-connection-example:
+
+Connection Example
+------------------
+
+This section shows how to configure your Laravel application's DSN by using a
+MongoDB Atlas connection string.
+
+To add your MongoDB DSN to your Laravel application, make the following changes:
+
+- Add the DSN as an environment variable in your project's ``.env`` environment
+  configuration file. Set the variable value to your Atlas connection string.
+- Add a connection entry for your MongoDB connection in the ``connections``
+  array of your ``config/database.php`` configuration file. Set the ``dsn``
+  value of the connection entry to reference the environment variable that
+  contains your DSN.
+
+The following examples show how to specify ``"mongodb+srv://myUser:[email protected]/"``
+as the connection string in the relevant configuration files:
+
+.. code-block:: php
+   :caption: Sample .env environment configuration
+
+   DB_URI=""mongodb+srv://myUser:[email protected]/";
+
+.. code-block:: php
+   :caption: Sample config/database.php connection entry
+   :emphasize-lines: 3
+
+   'connections' => [
+       'mongodb' => [
+           'dsn' => env(DB_URI), // uses the value of the DB_URI environment variable
+           'driver' => 'mongodb',
+           'database' => 'sample_mflix',
+           // ...
+       ],
+     // ...
+   ]
+
+.. tip::
+
+   To retrieve your Atlas connection string, follow the
+   :ref:`Create a Connection String <laravel-quick-start-connection-string>`
+   step of the Quick Start tutorial.
+
+.. _laravel-other-ways-to-connect:
+
+Other Ways to Connect to MongoDB
+--------------------------------
+
+The following sections show you how to connect to a single MongoDB server
+instance or a replica set not hosted on MongoDB Atlas.
+
+.. _laravel-connect-localhost:
+
+Connect to a MongoDB Server on Your Local Machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section shows an example connection string you can use when running a
+Laravel application and MongoDB server from the same machine, such as your
+local development environment.
+
+To connect your application to a MongoDB instance hosted on the same machine,
+you must complete the following tasks:
+
+- Download, install, and run MongoDB server.
+- Obtain the IP address and port on which your MongoDB server is running. If
+  you use the default settings of a local installation of MongoDB server,
+  the IP address is ``127.0.0.1``, and the port is ``27017``.
+- Set up your ``config/database.php`` connection to reference the environment
+  variable ``DB_URI`` for the value of the ``dsn``, as shown in the
+  :ref:`laravel-atlas-connection-example` section.
+
+The following example shows a sample connection string that you can add to the
+``.env`` file if your application connects to a MongoDB server running on the
+default IP address and port:
+
+.. code-block:: php
+   :caption: Sample .env environment configuration to connect to a local MongoDB server.
+
+   DB_URI="mongodb://127.0.0.1:27017/";
+
+To learn how to download  and install MongoDB server, see
+:manual:`Install MongoDB Community Edition </installation/#mongodb-installation-tutorials>`
+in the {+server-docs-name+}.
+
+.. _laravel-connect-replica-set:
+
+Connect to a Replica Set
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A MongoDB replica set deployment is a group of connected instances, or nodes,
+where the nodes store the same data set. This configuration of instances
+provides data redundancy and high data availability.
+
+To connect to a replica set deployment, specify each node's hostname and port
+number, separated by commas, and the replica set name as the value of the
+``replicaSet`` parameter in the connection string.
+
+This example, which shows the connection string you can add to your
+Laravel application's ``.env`` file to connect to a replica set, uses the
+following sample values:
+
+- ``host1``, ``host2``, and ``host3`` as the hostnames of the MongoDB nodes
+- ``27017`` as the port on which MongoDB runs on those hosts
+- ``myRS`` as the configured name of the replica set
+- ``myUser`` and ``myPass123`` as the credentials of a database user
+
+.. code-block:: bash
+
+   DB_URI="mongodb://myUser:myPass123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS"
+
+When connecting to a replica set, the library that {+odm-short+} uses to manage
+connections with MongoDB performs the following actions unless otherwise
+specified:
+
+- Discovers all replica set members when given the address of any one member.
+- Sends operations to the appropriate member, such as instructions
+  to write against the **primary** node. To learn more about the replica
+  set primary, see :manual:`Replica Set Primary </core/replica-set-primary/>`
+  in the {+server-docs-name+}.
+
+.. tip::
+
+   You are required to specify only one host to connect to a replica set.
+   However, to ensure connectivity when the selected host is unavailable,
+   provide the full list of hosts.
+
+To learn more about setting up a MongoDB replica set, see
+:manual:`Deploy a Replica Set </tutorial/deploy-replica-set/>` in the
+{+server-docs-name+}.
+
+Direct Connection
+`````````````````
+
+To force operations to run on a specific node in a MongoDB replica set,
+specify the connection information for the node in the connection string and
+the ``directConnection`` parameter with a ``true`` value.
+
+Direct connections include the following limitations:
+
+- DNS seed list connection format connection strings cannot be used.
+- Write operations fail when the specified host is not the primary.
+- When the host is not the primary, you must specify the  ``secondary`` read
+  preference in your connection options. To learn more about this limitation, see the
+  :manual:`secondary read preference entry </core/read-preference/#mongodb-readmode-secondary>`
+  in the {+server-docs-name+}.
+
+The following example shows the connection string you can add to your
+Laravel application's ``.env`` file to establish a direct connection to a
+secondary node in a MongoDB replica set. The example uses the following sample
+values:
+
+- ``host2`` as the hostname of the secondary node
+- ``27017`` as the port on which the MongoDB node listens on
+
+.. code-block:: bash
+   :caption: Sample .env environment configuration to enable a direct connection
+
+   DB_URI="mongodb://host2:27017/?directConnection=true&readPreference=secondary"
+
+