diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index 291947c5f..a850d44f0 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -15,6 +15,7 @@ Fundamentals :titlesonly: :maxdepth: 1 + /fundamentals/connection /fundamentals/database-collection /fundamentals/read-operations /fundamentals/write-operations @@ -22,8 +23,8 @@ Fundamentals Learn how to use the {+odm-long+} to perform the following tasks: -- :ref:`Manage Databases and Collections ` -- :ref:`Read Operations ` -- :ref:`Write Operations ` -- :ref:`Create Aggregation Pipelines by Using the Aggregation Builder ` - +- :ref:`laravel-fundamentals-connection` +- :ref:`laravel-db-coll` +- :ref:`laravel-fundamentals-read-ops` +- :ref:`laravel-fundamentals-write-ops` +- :ref:`laravel-aggregation-builder` diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt new file mode 100644 index 000000000..17b849ae9 --- /dev/null +++ b/docs/fundamentals/connection.txt @@ -0,0 +1,25 @@ +.. _laravel-fundamentals-connection: + +=========== +Connections +=========== + +.. toctree:: + + /fundamentals/connection/connect-to-mongodb + /fundamentals/connection/connection-options + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +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/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/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 ``