From 19bb87fad8014dac705af5d8640dfb5140d6d337 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 22 Apr 2024 13:17:55 -0400 Subject: [PATCH 1/2] DOCSP-35938: Connection Guide docs (#2881) * DOCSP-35938: Connect to MongoDB docs --- docs/fundamentals.txt | 4 +- docs/fundamentals/connection.txt | 25 ++ .../connection/connect-to-mongodb.txt | 355 ++++++++++++++++++ .../includes/figures/connection_uri_parts.png | Bin 0 -> 9609 bytes docs/index.txt | 3 +- 5 files changed, 385 insertions(+), 2 deletions(-) create mode 100644 docs/fundamentals/connection.txt create mode 100644 docs/fundamentals/connection/connect-to-mongodb.txt create mode 100644 docs/includes/figures/connection_uri_parts.png diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index f9e26b772..004930ad2 100644 --- a/docs/fundamentals.txt +++ b/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 ` +- :ref:`Configure Your MongoDB Connection ` +- :ref:`Databases and Collections ` - :ref:`Read Operations ` - :ref:`Write Operations ` diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt new file mode 100644 index 000000000..b1d11c58a --- /dev/null +++ b/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 from your Laravel application to a MongoDB +deployment and specify the connection behavior by using {+odm-short+} in the +following sections: + +- :ref:`laravel-connect-to-mongodb` + diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt new file mode 100644 index 000000000..7de96ad76 --- /dev/null +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -0,0 +1,355 @@ +.. _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 `, which explains connection + URIs and their constituent parts +- :ref:`laravel-database-config`, which explains how to set up your MongoDB + database connection for your Laravel app. +- :ref:`Connection Example `, which provides + examples that show how to connect to MongoDB by using an Atlas connection + string. +- :ref:`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 ` +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 ` +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-database-config: + +Laravel Database Connection Configuration +------------------------------------------ + +{+odm-short+} lets you configure your MongoDB database connection in the +``config/database.php`` Laravel application file. You can specify the following +connection details in this file: + +- ``default``, which specifies the database connection to use when unspecified +- ``connections``, which contains database connection information to access + one or more databases from your application + +You can use the following code in the configuration file to set the default +connection to a corresponding ``mongodb`` entry in the ``connections`` array: + +.. code-block:: php + + 'default' => 'mongodb', + +For a MongoDB database connection, you can specify the following details: + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Setting + - Description + + * - ``driver`` + - Specifies the database driver to use for the connection. + + * - ``dsn`` + - The data source name (DSN) that specifies the MongoDB connection URI. + + * - ``host`` + - | Specifies the network address and port of one or more MongoDB nodes + in a deployment. You can use this setting instead of the ``dsn`` + setting. + | To specify a single host, pass the hostname and port as a string as + shown in the following example: + + .. code-block:: php + :copyable: false + + 'host' => 'myhost.example.com:27017', + + | To specify multiple hosts, pass them in an array as shown in the + following example:: + + .. code-block:: php + :copyable: false + + 'host' => ['node1.example.com:27017', 'node2.example.com:27017', 'node3.example.com:27017'], + + .. note:: + + This option does not accept hosts that use the DNS seedlist + connection format. + + * - ``database`` + - Specifies the name of the MongoDB database to read and write to. + + * - ``username`` + - Specifies your database user's username credential to authenticate + with MongoDB. + + * - ``password`` + - Specifies your database user's password credential to authenticate + with MongoDB. + + * - ``options`` + - Specifies connection options to pass to MongoDB that determine the + connection behavior. + + * - ``driverOptions`` + - Specifies options specific to pass to the MongoDB PHP Library driver + that determine the driver behavior for that connection. + +.. note:: + + You can specify the following settings in the ``dsn`` configuration + as parameters in your MongoDB connection string instead of as array items: + + - ``host`` + - ``username`` + - ``password`` + - ``options`` and ``driverOptions``, which are specified by the option name + +The following example shows how you can specify your MongoDB connection details +in the ``connections`` array item: + +.. code-block:: php + :caption: Example config/database.php MongoDB connection configuration + + 'connections' => [ + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => 'mongodb+srv//myUser:myPass123@sample.host:27017/', + 'database' => 'sample_mflix', + 'options' => [ + 'maxPoolSize' => 20, + 'w' => 'majority', + ], + 'driverOptions' => [ + 'serverApi' => 1, + ], + ], + // ... + ], + +The following 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:myPass123@mongodb0.example.com/"`` +as the connection string in the relevant configuration files: + +.. code-block:: bash + :caption: Sample .env environment configuration + + DB_URI="mongodb+srv://myUser:myPass123@mongodb0.example.com/" + +.. 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 ` + 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 the 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 ` +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 ` + 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 ` 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 ` + 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" + + diff --git a/docs/includes/figures/connection_uri_parts.png b/docs/includes/figures/connection_uri_parts.png new file mode 100644 index 0000000000000000000000000000000000000000..d57165511438d2730a511d8d24f44a7bafda3dab GIT binary patch literal 9609 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 E06j{~lK=n! literal 0 HcmV?d00001 diff --git a/docs/index.txt b/docs/index.txt index e1331f6a2..88aee9d65 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -61,7 +61,8 @@ Fundamentals To learn how to perform the following tasks by using {+odm-short+}, see the following content: -- :ref:`Manage Databases and Collections ` +- :ref:`laravel-fundamentals-connection` +- :ref:`laravel-db-coll` - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-eloquent-models` From eea4950c8477bc2fb1f9926972cff79ee0ba72aa Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 22 Apr 2024 13:44:05 -0400 Subject: [PATCH 2/2] DOCSP-35941 connection options (#2892) * DOCSP-35941: Connection Options docs --- docs/fundamentals.txt | 9 +- docs/fundamentals/connection.txt | 8 +- .../connection/connection-options.txt | 349 ++++++++++++++++++ 3 files changed, 357 insertions(+), 9 deletions(-) create mode 100644 docs/fundamentals/connection/connection-options.txt diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index 004930ad2..250e82efa 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -22,8 +22,7 @@ Fundamentals Learn how to use the {+odm-long+} to perform the following tasks: -- :ref:`Configure Your MongoDB Connection ` -- :ref:`Databases and Collections ` -- :ref:`Read Operations ` -- :ref:`Write Operations ` - +- :ref:`laravel-fundamentals-connection` +- :ref:`laravel-db-coll` +- :ref:`laravel-fundamentals-read-ops` +- :ref:`laravel-fundamentals-write-ops` diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index b1d11c58a..17b849ae9 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -7,6 +7,7 @@ Connections .. toctree:: /fundamentals/connection/connect-to-mongodb + /fundamentals/connection/connection-options .. contents:: On this page :local: @@ -17,9 +18,8 @@ Connections Overview -------- -Learn how to set up a connection from your Laravel application to a MongoDB -deployment and specify the connection behavior by using {+odm-short+} in the -following sections: +Learn how to use {+odm-short+} to set up a connection to a MongoDB deployment +and specify connection behavior in the following sections: - :ref:`laravel-connect-to-mongodb` - +- :ref:`laravel-fundamentals-connection-options` diff --git a/docs/fundamentals/connection/connection-options.txt b/docs/fundamentals/connection/connection-options.txt new file mode 100644 index 000000000..9d873a406 --- /dev/null +++ b/docs/fundamentals/connection/connection-options.txt @@ -0,0 +1,349 @@ +.. _laravel-fundamentals-connection-options: + +================== +Connection Options +================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, data source name, dsn, authentication, configuration, options, driverOptions + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn about connection, authentication, and driver +options and how to specify them in your Laravel application's database +connection configuration. Connection options are passed to the {+php-library+}, +which manages your database connections. + +To learn more about the {+php-library+}, see the +`{+php-library+} documentation `__. + +This guide covers the following topics: + +- :ref:`laravel-connection-auth-options` +- :ref:`laravel-driver-options` + +.. _laravel-connection-auth-options: + +Connection and Authentication Options +------------------------------------- + +Learn how to add common connection and authentication options to your +configuration file in the following sections: + +- :ref:`laravel-connection-auth-example` +- :ref:`laravel-connection-auth-descriptions` + +.. _laravel-connection-auth-example: + +Add Connection and Authentication Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify connection or authentication options in your Laravel web +application's ``config/database.php`` configuration file by using one of the +following methods: + +- Add the setting and value as an array item in the ``options`` array item. +- Append the setting and value as a query string parameter on the connection + string specified in the ``dsn`` array item. + +To specify an option in the ``options`` array, add its name and value as an +array item, as shown in the following example: + +.. code-block:: php + :emphasize-lines: 6-10 + + 'connections' => [ + 'mongodb' => [ + 'dsn' => 'mongodb+srv://mongodb0.example.com/', + 'driver' => 'mongodb', + 'database' => 'sample_mflix', + 'options' => [ + 'appName' => 'myLaravelApp', + 'compressors' => 'zlib', + 'zlibCompressionLevel' => 7, + ], + ], + ], + +To specify options as parameters in the connection string, use the following +query string syntax formatting: + +- Add the question mark character, ``?``, to separate the host information + from the parameters. +- Add the options by formatting them as ``