From 49c65b1f328fae6b2c879bd9d659217a7e17d717 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 17 Apr 2024 10:33:27 -0400 Subject: [PATCH 01/15] DOCSP-35938: Connect to MongoDB --- docs/fundamentals.txt | 2 + docs/fundamentals/connection.txt | 25 +++ .../connection/connect-to-mongodb.txt | 172 ++++++++++++++++++ 3 files changed, 199 insertions(+) create mode 100644 docs/fundamentals/connection.txt create mode 100644 docs/fundamentals/connection/connect-to-mongodb.txt diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index f9e26b772..6245fd70e 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -15,12 +15,14 @@ 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:`Connection to MongoDB ` - :ref:`Manage 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..7d0aa757f --- /dev/null +++ b/docs/fundamentals/connection.txt @@ -0,0 +1,25 @@ +.. _laravel-fundamentals-connection: + +================ +Connection Guide +================ + +.. toctree:: + + /fundamentals/connection/connect + +.. 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 ` + diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt new file mode 100644 index 000000000..4cbe16388 --- /dev/null +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -0,0 +1,172 @@ +.. _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 ` describes connection URIs + and their constituent parts +- :ref:`Database Configuration File ` +- :ref:`Connection Example ` provides + examples that show how to connect to MongoDB by using an Atlas + connection string +- :ref:`Other Ways to Connect to MongoDB ` + 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, tells the +driver how to connect to MongoDB and how to behave while connected. + +Parts of a Connection URI +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example explains each part of a sample connection URI: + +.. figure:: /includes/figures/connection_uri_parts.png + :alt: Parts of a connection URI + +In this example, we use ``mongodb`` for the protocol, which specifies the +:manual:`Standard Connection String Format +`. +You can also use the :manual:`DNS Seed List Connection Format +` if you +want more flexibility in your deployment and the ability to change the +servers in rotation without reconfiguring clients. + +If you are using 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 are using 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 the +hostname or IP address and port of your MongoDB instance. In the +preceding example, we use ``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 two connection options: +``maxPoolSize=20`` and ``w=majority``. + +.. _laravel-database-config-file: + +Database Configuration File +--------------------------- + +TODO: +This section will show how to add the connection URI to your DSN setting in +the config/database.php file. + + +.. _laravel-atlas-connection-example: + + +Connection Example +------------------ + +The following code shows how you can create a client that uses an Atlas +connection string and the {+stable-api+} version, connect to MongoDB, and +verify that the connection is successful. + + +TODO: + + +.. tip:: + + Follow the :ref:`Create a Connection String ` + tutorial in the Quick Start to retrieve your Atlas connection string. + +.. _laravel-other-ways-to-connect: + +Other Ways to Connect to MongoDB +-------------------------------- + +If you must connect to a single MongoDB server instance or replica set +that is not hosted on Atlas, see the following sections to find out how to +connect. + + +.. _laravel-connect-localhost: + +Connect to a MongoDB Server on Your Local Machine +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TODO + +.. _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 set of data. This configuration of instances +provides data redundancy and high data availability. + +To connect to a replica set deployment, specify the hostname and port numbers +of each instance, separated by commas, and the replica set name as the value +of the ``replicaSet`` parameter in the connection string. + +In the following example, the hostnames are ``host1``, ``host2``, and +``host3``, and the port numbers are all ``27017``. The replica set name +is ``myRS``. The following code shows the connection URI for the replica +set with these specifications: + +.. code-block:: none + + mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS + +When connecting to a replica set, the driver takes the following actions by default: + +- 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 only required to specify one host to connect to a replica set. + However, to ensure connectivity when the specified host + is unavailable, provide the full list of hosts. + +Direct Connection +````````````````` + +To force operations on the host designated in the connection URI, +specify the ``directConnection`` option. Direct connections display the +following behavior: + +- They don't support SRV strings. +- They fail on writes when the specified host is not the primary. +- They require you to :manual:`specify a secondary read preference + ` when the + specified host isn't the primary member. To learn more about these + replica set members, see :manual:`Replica Set Secondary Members + ` in the Server manual. From f3f89c7e1912f09f4647a1729ed1a1c2d1de57ad Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Apr 2024 17:35:54 -0400 Subject: [PATCH 02/15] rework examples --- .../connection/connect-to-mongodb.txt | 180 +++++++++++++----- .../includes/figures/connection_uri_parts.png | Bin 0 -> 9609 bytes 2 files changed, 128 insertions(+), 52 deletions(-) create mode 100644 docs/includes/figures/connection_uri_parts.png diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 4cbe16388..c3500a193 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -27,7 +27,7 @@ This guide includes the following sections: - :ref:`Connection URI ` describes connection URIs and their constituent parts -- :ref:`Database Configuration File ` +- :ref:`Laravel Data Source Name ` - :ref:`Connection Example ` provides examples that show how to connect to MongoDB by using an Atlas connection string @@ -40,8 +40,8 @@ This guide includes the following sections: Connection URI -------------- -A **connection URI**, also known as a connection string, tells the -driver how to connect to MongoDB and how to behave while connected. +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 ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -54,17 +54,16 @@ The following example explains each part of a sample connection URI: In this example, we use ``mongodb`` for the protocol, which specifies the :manual:`Standard Connection String Format `. -You can also use the :manual:`DNS Seed List Connection Format -` if you -want more flexibility in your deployment and the ability to change the +If machine that hosts your MongoDB deployment supports it, you can use 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 you are using 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 are using an authentication -mechanism that does not require a username and password, omit -this part of the connection URI. +If you are using 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 are using 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 the hostname or IP address and port of your MongoDB instance. In the @@ -75,51 +74,101 @@ The last part of the connection string specifies connection and authentication options. In the example, we set two connection options: ``maxPoolSize=20`` and ``w=majority``. -.. _laravel-database-config-file: +.. _laravel-data-source-name: -Database Configuration File ---------------------------- +Laravel Data Source Name +------------------------ -TODO: -This section will show how to add the connection URI to your DSN setting in -the config/database.php file. +In Laravel, you can specify your database connection details in a connection +string, which is called a data source name (DSN). {+odm-short+} lets you use +a the MongoDB standard connection string format to specify the connection +details and options. +The next sections provide following sections provide common ways of specifying +MongoDB connections. .. _laravel-atlas-connection-example: - Connection Example ------------------ -The following code shows how you can create a client that uses an Atlas -connection string and the {+stable-api+} version, connect to MongoDB, and -verify that the connection is successful. +This section shows how you can configure your Laravel application's DSN to +use 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 value of the variable to your MongoDB connection + URI. +- 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:myPassword123@mongodb0.example.com/"`` +as the connection string in the relevant configuration files: -TODO: +.. code-block:: php + :caption: Sample .env environment configuration + DB_URI=""mongodb+srv://myUser:myPassword123@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:: - Follow the :ref:`Create a Connection String ` - tutorial in the Quick Start to retrieve your Atlas connection string. + 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 -------------------------------- -If you must connect to a single MongoDB server instance or replica set -that is not hosted on Atlas, see the following sections to find out how to -connect. - +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -TODO +This section shows an example connection string that you can use when you +run 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. To learn how to install MongoDB, see + :server:`Install MongoDB Community Edition `. +- 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 MongoDB + ``dsn`` as shown in the :ref:`laravel-atlas-connection-example` section. + +The following example shows a sample connection string that you can add to +``.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/"; .. _laravel-connect-replica-set: @@ -134,39 +183,66 @@ To connect to a replica set deployment, specify the hostname and port numbers of each instance, separated by commas, and the replica set name as the value of the ``replicaSet`` parameter in the connection string. -In the following example, the hostnames are ``host1``, ``host2``, and -``host3``, and the port numbers are all ``27017``. The replica set name -is ``myRS``. The following code shows the connection URI for the replica -set with these specifications: +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: -.. code-block:: none +- ``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 ``myPassword123`` as the credentials of a database user - mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS +.. code-block:: bash -When connecting to a replica set, the driver takes the following actions by default: + DB_URI="mongodb://myUser:myPassword123@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+}. + set primary, see :manual:`Replica Set Primary ` + in the {+server-docs-name+}. .. tip:: - You are only required to specify one host to connect to a replica set. - However, to ensure connectivity when the specified host - is unavailable, provide the full list of hosts. + You are required to specify only one host to connect to a replica set. + However, to ensure connectivity when the specified 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 on the host designated in the connection URI, -specify the ``directConnection`` option. Direct connections display the -following behavior: - -- They don't support SRV strings. -- They fail on writes when the specified host is not the primary. -- They require you to :manual:`specify a secondary read preference - ` when the - specified host isn't the primary member. To learn more about these - replica set members, see :manual:`Replica Set Secondary Members - ` in the Server manual. +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 +specify the ``directConnection`` parameter with a value of ``true``. + +Direct connections include the following limitations: + +- DNS seedlist SRV 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 zcmd6NXEYp6xVI$#kcQ+h2o}*xl;~Cs!Rn%S646#!tg_J)BKop=7gmcX(XAT2tP;Hw z?6S>Jmw^PxqYn%X{8)?z!)Ln3*%}`OPzPo_U_%neca-Aks&)kBEqfNL7>-bcl%l zf#25G9^AXlznaU$+!ilCD(h$v5&5ta5q$Db2A0TQ&AJ21f-;$w^UCQF8HcjgF4i)YN?W@Bm1X4aW`)jF2O zWe$Fl@4WmO;5mF*HbXdws&nqS7_D`E18=YknA-OC?w+e%^#_}ZzXUA^wK^U*N&UaW zShY+<%EhsE1O(dO(D~^;j2iXex$zh1DnB6XWU%&ORziT#TX#yy((rbmWr_46Za(G5)o{V70_uvjEe6RvJjj!6w^Z^pUjW-9 zn>x%P)yK2l@`3987KuudevbT{R_e`Lu5Kp3HM16`<$iWTpRK&QvD6F{Y`w3zj^;5X zb!iQV>%0gWGqH{oFJq6~^fi?x+)Br02O9jRiV-N&oX5CA#t=$?`NakdJp_0{UvPSg(+FaFQ7IO}(bue`xW^#v|o+VRW|4{X1i zzGK}`X&!PeDXF}~3i_E&D*>BWG-#v)7B`iRehDAfm)W=ntjuomP*-2wZeiL^ zIL_8&DpPN{M0}6(8)2LrAwmBJPuNuw?o769lFJ&NyI=K0*75>cwcwSl+j^4erDXK@ zzz~7ZY_Xe%kz@wcSAW@NQt)EO_*NA-gjnxwF^UGp%`IzWN+^`^M}0ui5<9O{&A)dB zw>}6KF>R^QO5rBhBAm0d<4N9?IH^5`#byE1pfV~?I|UDje|plCWEgc&wb2ov%?HqqwY*8P^T33x-pt@xp4IxC@pdlE zoo2E*CyIg2RWt@6VgYA2UhVf!WHGh+U_?PpY2$-Ra56|OwX_*$9aeO5>P)Y>87&@A zawwz+^XAFh77SI=%^=A-fM181i$!1IK~M4q`ljBR{=1c!vPzo5lXOX+yv=;M++*A^ zihJt%&IT*k|2#0^ftoxFK9&;p4g5qeAlDIhnOt#WUpy!D-tq}+qI#ZlJ4H;^A%6{!Md#jz~XAcC(|`aE!&1}$uT;2Tia8`&kXv{bjOdb-s>I`53ECnX|J}* zJ!{CrpV#b9@@uLf4qmjBsUFe52oAxaGP6v#W?P`X(!vpQ?}&Vho2O(PGI5J}j3j+C zj?A(_3CyN49T=Il8GGeo8~OxMnaU~e@1vuQX%LLaWr>^3PXJJf0KP&|pn{Meo$o6CfC*r4Bmz|D1xv&j! z@87?z5f`NFPGohsAs>@@CE|>|%R@xL=+f`?p`Rr~}0fI@ge{k7sd6=r5f#aiGTiNqns7 zJdg<({InTl7rUY=ixa!p&B#hmFGZVJag9g`V|wTCm1d2c-x<--0V@J_L2S^Fn@ubd$U$+Y88iPa_tBW>e4K89m``^m zK+(nm_|`Gdp93^Wrzwi`d6TcBxUBn4m=?tsT+Y?OEvLzOw)(EYWKv!~`z46N?Tp)+ zTf1-k1+AzLX#XW10l0s&(1)np_rcNe)&vi$nWfmqNg9e1NT7M7Uue~6+dXriuVc=jn<7H7(sS9>8 z^ec{MN!QaSsUrp!%Ogt06P#1eh~==FSe*5Z?EZ_5=~yJ|*A@Ba2vb1#=|dQHjqimR zA&(1`79DQCZPvgCJyfVPaC?_L%J@$IsTOt|9A~ zgwcdF#R5JmN8%w`1WPfI@P=8BuAq)ppH5^%h!7%|*7d%TvUAK&@3-*!GD&Y!hl2TM z?t#|2aLz8lMVR%@x;|%UjcL_fWyo{WG&WTiA@w|m$eq}lbU7Z7Afk(+k2WxWafBND=alRjVskIZ^53;^_25 z`{lF?*|&Xzwz2j&I?IBxhSPc;XS1Z}Z$+a?P7vD69at<&;tS~eK9rVT?+lI37Zmv` zeU3=l6~V*Ci_r&(KHE~gBPNd}Vw6K101ex=baK6Lr|BR`4sQnZG_MeK#HRy5C6=FB}~ zVJ2Pl3vJDuvoDE;3+k1?5hWk|QD|wOpQh^BYlLcpbHcRz*G``w+Iph{1l4D|4-O~% zoC({FuT3cm{H@w%MHP#>l1kEy|kgqg@HS_`9YiG6vuLVO$MW{2T&dMucT?1H zk_yXXU-KI5p2@7AW@J@K3}MKgsdx6DA4>=MVoGRyXFcBGbjDJ3(?CLpb%jryXAy7s z&lj~NU=*fRUUGeQxHN-~opAnQRqP@q<^3~*!d*s4*D?*Dwb^#7pr^Xuj}`QG#Ue6{+FyLvv=ax77}m;$D-RX>P_#Vr3aNB(J2`5K=6}w1 zkzLAJIcX>9P`$I%pApXGY$Oz0v-sEybLppIyrPEUZB(1Z&e(&ThSN#I27S}@7$f*( zz*kfR|9Guy(;K+Q`^H0T9FU_Z*}TpMk1g7z>~>64ijHia3kl$hrvpM8C9MhRQz8;x zG_=GbXWSoa9}m9te+lA~hVWH&=QrUxfp(1~#cyP)(Jk3e%e?ai+z7=G8$_1?2TfW9 z7^DfN;C~^isdDLOf#`U|$`{L> z(L(c-LihT1sHVgMw)C3>>~X7|{15Ca@5yRUJ&5c_Yc7@gqFzkY@(xY>GI7_QaI;lSX;@Eq9v9ql3A8y|OKskFA*~XJm z66o{MF^hdAl9LI4q1F3uc-9~n-(W4h4mrB2WYPJ=6B2RASEWbVfzeKJz%tz3>jaeQ z?}GV%ViY3nZrDI|RrHHjDpf@u|E7q(k;c6i9xs{+r#o+@wE*{z7_^Wr>n`rRrv3Ky zBk+-1yHLN)#_DI^@1r7w3%G|`$KY%+x%kXC*Yuy>_O5=(7S<4oi(SZ0nE!GeO$D`L z61$lb-KIjZOc|Ig>biQ0cF*gO#2uu9ky))Jf0wis3Qh3-X&8eE;~3}*D>$s-1<3M% z+zD^s3{NH@7@X}dQP&XJPr^p-LTcDdz>znEQ2D$heGVY^fT5Q9?=qYn^Gz(UAzmn_~z z8p^45&hQygbx)-##J_G^7*SWDs@^hy`z8A=PKT@i{9p=8F>>+@Q&RGMi)4j0?96_o z6U@$1R}lMnSph&fSr2XZrvhmdl*rl31oeh;xl$|E`;M-nGOCN|kkmj$ZdKm+_XrRJ zdZgc!Lc@kcaUzsO7~4xdVG={Hb4q3nUaw7a56yd&ja)L66P!AMVw{ebg@j}5KFTDq zh)I`P{a$nxU7Fn}eV{ut9~oX)`D&@o0b)TrE@w08mLvN#c5gL_Eec{bcf9aGqo9Ar zykxHFUQjYt?5Yr>jE34<0Zkf(JM@lA0pQ2l1gfTVaB*!2k`%Zia^UnEJ#_Tf0A9~p z`S1jx_7LODjEqOs`vMb=+)MrDRCg9iAQ=0nyypg_K$BiCQt*o>TD0M0Bcndg2G;e* zy57Jj|D+-2L~7#d&Gz})e4e5a4+rL;a0&`cA|07^5XGa^X!R zn+@o}?S5xF`UO(UP>Z>DwHk*%)AciafwMl2had=!;=1yXLllcEC=y(_tT|kFdD|AQ zxuv;cWMhU;G3-7)x-f#zi};_G>};w~5+{&j!}493KTfmKep8eT4@#P9@{ALznQ+qc zuiGgH5oF@~kF7p63^?wx$GKYUrtP(KVDV+!1^knK4|$m~RpMw``%f-`thGw|<*6qB z-cO9Fpge)IqFbogbpB+dVm|^$`6uPbmQ3M!AEqaV=rw@QxtE?x2=)5@uPbj%-!Bxd zAJcD;ReT|z=dKP)N2$Ky0nLA}*J1|czHLSdH1_({EzF!I)<8F?Dun{E#W!C7Zm^8E z0r|j{u8ps&pHL$_BVK9Homv4^^^8yKTff2TFh6J$X{h6n88w8;hsgp*6Tky<(7;5Z zhTAdsfI1zhA}Sq3UH(r(r7ycvum{0-)=Ui3t0gQ}w|T~7rVAGwYho)vOs=AkrQ#{- z3wj+A40KDR+*MBl!>cspxp_?WM*`+v3r73!+B{D?!ZZBn7L@aN%v;A*)0&}8F>h&LO{hILO zi|k;!vF`XiNH+DsW^mTM;sze+=YlupU5~!#Pb+*P!j;9RB9p*UV=MVkmdxxM)m03p zC>xd5sfZN=^9Pe$0^RPz_1XCzXL+F#S*VF*{E}d5UN>Bz)bq3s_Qldz=@cl8xEIeB z5K;^e^$Mu@J-&7Q5qOZ}&FEW@s(6&%o7B3i#PDH7ArN0RmigzMjC{Xw<4RM%I$ zkv7f79BIsjt!XY|TaCxzkpiZZrp@b~rG`uf)$emC&1&UlBcm^$=;-ZI&uNIdt%;4U zUVx+L0Ryj?9OR~njZM*8Iy*H0J+x2D0nCa$5?kwaaz$p4I{3amK2b`XOe`Tzx+C47 z#I4`8Vn*j0+yKLwmCWdOh`*Rglk1?K@YCgIll94c^-nhPL$_i+if&e@-J+~3Zuj@N z`^v=kdZ~*YojKIDO%a65H58UX710M zQ}{G;EFr7LU3F|Ed62qgPft;_==GYo4vd{JER9g*Qu4a>p>axRT2_ zPxZO>5ouuD*=lL__fv2KH)x~^TsLFrNdrAZ@9TaZW^#Xj($Riv9fP65f5N-Z(TRIp z60bl>BW0Xk8)DPTsL>l#7 z;JL63%Is2cOWG`XnJev?^J5SP7MJhwKhK~2e?sH^A29Zj&~Yp%zqcs2Svk`6gG905@r4k+o-7$S(Bw zCCL01kZ9{X-h7AwQ{?ytKD(CO*o>YD26&S8YR_Fl>tI0NSY+89phNn9i6V!Ni@XFm z6aMFfc#VM@9AH!1V5W6vx`W#4(igI-b3<1pTaC7cb6Gy#Lvx}SXRxWj|2^gW9jPAa zHl?8)S-p?qY=PFe30(b%@|*lsZj0-dy?MSt9d*->`W}xdIAR_gypCz5E-*H4Jr4Uh zj*(4>sn9_E9p4ZztCEtH`f+H9{xgum-)G$T-17DHtMwp5cfW!~PkFdZR587=m}dIK zc_`NY#5hL1v_t|Z(T}_{td)6c{VgIiGG`LX>9g_F>lBQwugVO|UUHnr4f}op;3F^JObrvX5p(F>vYyos zJ+jf{$sL;K^Bc>bPzTlUn%Z7|Utd)jp&mcs!3{^>9qfRe8=ju=;IcvXs#(MUuGuA! z{4j5%?OaYLbq(eD!9!zf=BE)#k};;M_iWB$QsU^-(^f>|FtbFJaXAx+^_>N`Qr8hQ zWi)X}^k_?QxWbTEQw|PwG|f`$=dg5Lm*OqES)xtyWjp$|PVL?o=p?#592Mc-GUjB~ zY0R=erhtULDg(4Tbnf&$|2n1*CU9 zv;aBq2?+^xCzX}jP(N~%RQ+|6{v#ea64jcbeaN_dV{5Ah0kmAY0VU`+ijxz#!I15V z63S#2<6dH8p?a8b{tQ(*#YJf<6m+5N*S1atee#(UM0syuJ=J9!%Ss;dX)lD%uE*y$v8&O7 zG8;a1S&tup_dRlLyWg{}Ly5cfq`+>PgBA2sO`XoRi#W4hXs-h*oTTbev*5BZha*~Z;FWS;UsZrsC-=_i;^Q;+V&vdDJBN&Hn>Z2) z&&wZew2m*#1A8`Y`F$z^R<4nZEl~d){h!q^)j}(*(G@ROMjn3y1#FBnMv5MdaHjMl zWE^-1nOFBbVo~M5{))jC{TZc2qgeX3^QR&UQ^xnW{Fl-I8!zU_2J}3+j&;K8kixNG ztw{}i>H^XA!l&dduB+S1vD^Nw$u@I^_}p9D%%rlF%;#DyJ_7XN`jLRw!-Q?deEpnc zv2#vw>7SDOV#88zCcp&l^%h@vi2wxX!mzU)~4yAums3(L! z7U|tseXl)C&8U)nG3rWlCiHcBZxX|KVy+8eRVEn{{vNmVXq{)`3D<%e;J@I9k+k~+ zcZb#1AFfw3fkyMf|BBqT`=+5%&Yr0H_I|kyn@Gsxh)9oeti#;yILutc)+tpZ&^r4+?YEW;YC8a1(=8XZP)fJXSpSyZVZ!-OwR@4D^-pyoUOwmeL{t0r~(juC_806z<_>6Cj-%k z^T|N@G~s28y@;cTR|{7ii`uo%tVXvb|;=8p`wgT5W%VdNYZ#n@OaLp0 z#JI7Ap?kH+L@ELK?8eu=_ZjS%6Aa6kGj>gwctFVz_>JyT@mn1S$Vc_E|znmIE0=6AfM;`iN)?#PVVlV}QHB{aLKP$M$I!0jO( z2?SsSfJ>PQ+V~TR8kHe7#tol%oF)@H3KzP)T#xca&TKcOuT?^arVgRjnVwR^w$*z9 z93WAWWGgL4o3Yo}bNgSm=w1uXy8EsX7<+z|9%!ecLcR#;{X#o{`c5qgaffM>8=4Ap z_I>NLNb z)q?G&>*|0U6Bhg?65Z1QUV9|gKa>fGjwyRDJUc8AHsQ|pFC1z6SKS=-c}gzdEAHZf z){n?>w=_|;FSgN%h#PQTPt0gGzhHAh-Ro(GXlaxrlhzRA%yYYRa_P!0d47EdAgv;? zoEz{@b>y+$=0uky2P`V<6>$;G$Fsl$rS*Jr)_{a_SjEF=~GzDe*8WG!vlrPX< zqUEY#faibs??Deqp5p0A?jNE*1Fr5U`1XLGRJ65fosVrjx)BWX`tJ_xsaDHLjfLW~ zV^Ph=>Z5mwu7g~f>5*aCgvmcG#myF8e${w&XK7d}?RN4G>beGiEpR*8 z1%FGnAR@{NWtbAmg?XcrL-!k-ly*ujo5v1aQ3vyz67t$xho;q0!=g|=6Pek>1J8!j zG#fu5BD%hZVDa}(!9U->BrM8OisXYnXPz!79wdndcx{I*QFw_M`X~%1WG~AWa3r6d z05UNuV}@g+KdtW&-Mr)m9VFGtTb@l5hOcM~57C;7{%cF4qFBo6{fSooV2c~%@OG;L zf289smjlt~K=MSElS2LY$Q^}Iy8SV(X0-v~#Zjus0jPK4yhzivoobAeG^$f}KgfmX zce>8Jl$%I?Pl3gwlj(&DUqiFi8s+8X)@yyJ1>7feuToq}`X14qR2@`d_aLrky9z*W z4Y{>#^Nq<+cUS(D$Fo(EX7i@EEI!d^J5(}~LF2x;9^6)n!lMO&l((2|(mG;OR;O*& zhp_HCL@o~9{{6XWiw2mV4N`wZAoZ~Je$RjhyG$yBHav3?1qZYR?PNomC6LrxjMTo?(nC6BwF|IPS3Q!T?Y0J^A63fR_@cPcp8m@{UJGVN zQ$kN_;dh7VQ_@@;ZFA9|fm4y{!|vBv{ViDq1_4$;iN3F}@_nUWRZZ{G?CN6j-hPx~ zyOkof+L#;~T?i(8j=x~>Q8PX47Qf*}AsRzuGy83wGOg|seKvH544K93iFy;gQNxuo zkqrRu5SbwNJ4KxOh>5CuIh(3l_Qn4D{rumr`w88Uz@#np?M}pw{u7OgqNYNb{QIE) E06j{~lK=n! literal 0 HcmV?d00001 From 06b7b21e9d08b51c5b9b5a0e429abc40e72dc90d Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Apr 2024 17:40:32 -0400 Subject: [PATCH 03/15] RST fixes --- docs/fundamentals.txt | 4 ++-- docs/fundamentals/connection.txt | 2 +- docs/fundamentals/connection/connect-to-mongodb.txt | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index 6245fd70e..3ddf01982 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -22,8 +22,8 @@ Fundamentals Learn how to use the {+odm-long+} to perform the following tasks: -- :ref:`Connection to MongoDB ` -- :ref:`Manage Databases and Collections ` +- :ref:`Connection Guide ` +- :ref:`Databases and Collections ` - :ref:`Read Operations ` - :ref:`Write Operations ` diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index 7d0aa757f..005461e02 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -6,7 +6,7 @@ Connection Guide .. toctree:: - /fundamentals/connection/connect + /fundamentals/connection/connect-to-mongodb .. contents:: On this page :local: diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index c3500a193..819f99e9d 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -154,7 +154,7 @@ 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. To learn how to install MongoDB, see - :server:`Install MongoDB Community Edition `. + :manual:`Install MongoDB Community Edition `. - 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``. From ef9809f32dea05b3850b86f191fb2a99486b64de Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Apr 2024 17:45:05 -0400 Subject: [PATCH 04/15] rename --- docs/fundamentals.txt | 2 +- docs/fundamentals/connection.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index 3ddf01982..9872a02fe 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -22,7 +22,7 @@ Fundamentals Learn how to use the {+odm-long+} to perform the following tasks: -- :ref:`Connection Guide ` +- :ref:`Connections ` - :ref:`Databases and Collections ` - :ref:`Read Operations ` - :ref:`Write Operations ` diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index 005461e02..fab7e26af 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -1,8 +1,8 @@ .. _laravel-fundamentals-connection: -================ -Connection Guide -================ +=========== +Connections +=========== .. toctree:: From 224e925211146a91564073a607393511b9398e15 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Apr 2024 18:04:02 -0400 Subject: [PATCH 05/15] grammar fixes --- .../connection/connect-to-mongodb.txt | 84 ++++++++++--------- 1 file changed, 44 insertions(+), 40 deletions(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 819f99e9d..93b2427ca 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -25,15 +25,16 @@ MongoDB instance or replica set deployment by using {+odm-short+}. This guide includes the following sections: -- :ref:`Connection URI ` describes connection URIs - and their constituent parts -- :ref:`Laravel Data Source Name ` -- :ref:`Connection Example ` provides - examples that show how to connect to MongoDB by using an Atlas - connection string +- :ref:`Connection URI `, which explains connection + URIs and their constituent parts +- :ref:`Laravel Data Source Name `, which explains + how to specify a connection to MongoDB. +- :ref:`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 ` describes ways to connect to MongoDB deployments that are not hosted - on Atlas + on Atlas. .. _laravel-connection-uri: @@ -59,20 +60,22 @@ If machine that hosts your MongoDB deployment supports it, you can use the for greater flexibility in your deployment and the ability to change the servers in rotation without reconfiguring clients. -If you are using password-based authentication, the part of the connection +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 are using an authentication mechanism that does not require a username +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 the -hostname or IP address and port of your MongoDB instance. In the -preceding example, we use ``sample.host`` as the hostname and ``27017`` -as the port. Replace these values to point to your MongoDB instance. +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 two connection options: -``maxPoolSize=20`` and ``w=majority``. +options. In the example, we set the following connection options and values: + +- ``maxPoolSize=20`` +- ``w=majority`` .. _laravel-data-source-name: @@ -80,26 +83,23 @@ Laravel Data Source Name ------------------------ In Laravel, you can specify your database connection details in a connection -string, which is called a data source name (DSN). {+odm-short+} lets you use -a the MongoDB standard connection string format to specify the connection -details and options. +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 following sections provide common ways of specifying -MongoDB connections. +The next sections provide common ways of specifying MongoDB connections. .. _laravel-atlas-connection-example: Connection Example ------------------ -This section shows how you can configure your Laravel application's DSN to -use a MongoDB Atlas connection string. +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 value of the variable to your MongoDB connection - URI. + 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 @@ -146,22 +146,22 @@ instance or a replica set not hosted on MongoDB Atlas. Connect to a MongoDB Server on Your Local Machine ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section shows an example connection string that you can use when you -run Laravel application and MongoDB server from the same machine, such as -your local development environment. +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. To learn how to install MongoDB, see - :manual:`Install MongoDB Community Edition `. +- 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 MongoDB - ``dsn`` as shown in the :ref:`laravel-atlas-connection-example` section. + 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 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: @@ -170,18 +170,22 @@ default IP address and port: 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 set of data. This configuration of instances +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 the hostname and port numbers -of each instance, separated by commas, and the replica set name as the value -of the ``replicaSet`` parameter in the connection string. +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 @@ -209,7 +213,7 @@ specified: .. tip:: You are required to specify only one host to connect to a replica set. - However, to ensure connectivity when the specified host is unavailable, + 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 @@ -221,11 +225,11 @@ 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 -specify the ``directConnection`` parameter with a value of ``true``. +the ``directConnection`` parameter with a ``true`` value. Direct connections include the following limitations: -- DNS seedlist SRV connection strings cannot be used. +- 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 From abcc44ab0dbf0f6aa5f1546ed94d626d4ed8c914 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Apr 2024 18:24:03 -0400 Subject: [PATCH 06/15] tweaks --- .../connection/connect-to-mongodb.txt | 41 ++++++++++--------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 93b2427ca..3014fa5d2 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -25,12 +25,12 @@ MongoDB instance or replica set deployment by using {+odm-short+}. This guide includes the following sections: -- :ref:`Connection URI `, which explains connection +- :ref:`Connection URI `, which explains connection URIs and their constituent parts - :ref:`Laravel Data Source Name `, which explains how to specify a connection to MongoDB. - :ref:`Connection Example `, which provides - examples that show how to connect to MongoDB by using an Atlas connection + examples that show how to connect to MongoDB by using an Atlas connection string. - :ref:`Other Ways to Connect to MongoDB ` describes ways to connect to MongoDB deployments that are not hosted @@ -47,19 +47,21 @@ A **connection URI**, also known as a connection string, specifies how Parts of a Connection URI ~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example explains each part of a sample 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 example, we use ``mongodb`` for the protocol, which specifies the -:manual:`Standard Connection String Format -`. -If machine that hosts your MongoDB deployment supports it, you can use the +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. @@ -68,7 +70,7 @@ 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 +``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 @@ -83,8 +85,9 @@ 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. +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. @@ -105,13 +108,13 @@ To add your MongoDB DSN to your Laravel application, make the following changes: value of the connection entry to reference the environment variable that contains your DSN. -The following examples show how to specify ``"mongodb+srv://myUser:myPassword123@mongodb0.example.com/"`` +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:: php :caption: Sample .env environment configuration - DB_URI=""mongodb+srv://myUser:myPassword123@mongodb0.example.com/"; + DB_URI=""mongodb+srv://myUser:myPass123@mongodb0.example.com/"; .. code-block:: php :caption: Sample config/database.php connection entry @@ -147,7 +150,7 @@ 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 +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, @@ -183,8 +186,8 @@ 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 +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 @@ -194,11 +197,11 @@ 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 ``myPassword123`` as the credentials of a database user +- ``myUser`` and ``myPass123`` as the credentials of a database user .. code-block:: bash - DB_URI="mongodb://myUser:myPassword123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS" + 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 @@ -233,8 +236,8 @@ Direct connections include the following limitations: - 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+}. + :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 From b78f5feed98069257bb9fe815c31dc08904a4ffe Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 19 Apr 2024 12:10:50 -0400 Subject: [PATCH 07/15] add section on the database config file --- .../connection/connect-to-mongodb.txt | 71 +++++++++++++++---- 1 file changed, 58 insertions(+), 13 deletions(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 3014fa5d2..0f1b02b73 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -27,14 +27,13 @@ This guide includes the following sections: - :ref:`Connection URI `, which explains connection URIs and their constituent parts -- :ref:`Laravel Data Source Name `, which explains - how to specify a connection to MongoDB. +- :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:`Other Ways to Connect to MongoDB ` - describes ways to connect to MongoDB deployments that are not hosted - on Atlas. +- :ref:`laravel-other-ways-to-connect` describes ways to connect to MongoDB + deployments that are not hosted on Atlas. .. _laravel-connection-uri: @@ -79,15 +78,61 @@ options. In the example, we set the following connection options and values: - ``maxPoolSize=20`` - ``w=majority`` -.. _laravel-data-source-name: +.. _laravel-database-config: -Laravel Data Source Name ------------------------- +Laravel Database Connection Configuration +------------------------------------------ -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. +{+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 default database connection to use when + unspecified +- ``connections``, which contains dataabase connection information to access + various 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: + +- ``driver``, which specifies the database driver to use for the connection +- ``dsn``, the data source name (DSN) that specifies the MongoDB connection URI +- ``host``, which you can use instead of the ``dsn`` setting to specify the + network address of one or more MongoDB nodes +- ``database``, which specifies the name of the MongoDB database to read and + write to +- ``username`` and ``password``, which you can optionally include to specify + your database user's credentials to authenticate with MongoDB +- ``options`` and ``driverOptions``, which specify connection options to + pass to the MongoDB driver + +The following example shows how you can specify a your MongoDB connection +details in a ``connections`` array entry: + +.. code-block:: php + :caption: Example config/database.php MongoDB connection configuration + + 'connections' => [ + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => 'mongodb+srv//myUser:myPass@sample.host:27017/', + 'database' => 'laravel', + 'options' => [ + 'maxPoolSize => 20, + 'w' => 'majority', + ], + 'driverOptions' => [ + 'serverApi' => 1, + ], + ], + // ... + ], The next sections provide common ways of specifying MongoDB connections. @@ -122,7 +167,7 @@ as the connection string in the relevant configuration files: 'connections' => [ 'mongodb' => [ - 'dsn' => env(DB_URI), // uses the value of the DB_URI environment variable + 'dsn' => env('DB_URI'), // uses the value of the DB_URI environment variable 'driver' => 'mongodb', 'database' => 'sample_mflix', // ... From 80ddf489f947fbb8c06c70ebdd17b82c78f9cb6b Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 19 Apr 2024 12:21:59 -0400 Subject: [PATCH 08/15] fixes --- docs/fundamentals/connection/connect-to-mongodb.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 0f1b02b73..75d8fd0c1 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -89,7 +89,7 @@ connection details in this file: - ``default``, which specifies the default database connection to use when unspecified -- ``connections``, which contains dataabase connection information to access +- ``connections``, which contains database connection information to access various databases from your application You can use the following code in the configuration file to set the default @@ -122,9 +122,9 @@ details in a ``connections`` array entry: 'mongodb' => [ 'driver' => 'mongodb', 'dsn' => 'mongodb+srv//myUser:myPass@sample.host:27017/', - 'database' => 'laravel', + 'database' => 'sample_mflix', 'options' => [ - 'maxPoolSize => 20, + 'maxPoolSize' => 20, 'w' => 'majority', ], 'driverOptions' => [ From 29eb1dd8ad712b1ac65e3d91f411c0e07a6e853e Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 19 Apr 2024 12:28:00 -0400 Subject: [PATCH 09/15] update example password --- docs/fundamentals/connection/connect-to-mongodb.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 75d8fd0c1..d322c6a05 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -121,7 +121,7 @@ details in a ``connections`` array entry: 'connections' => [ 'mongodb' => [ 'driver' => 'mongodb', - 'dsn' => 'mongodb+srv//myUser:myPass@sample.host:27017/', + 'dsn' => 'mongodb+srv//myUser:myPass123@sample.host:27017/', 'database' => 'sample_mflix', 'options' => [ 'maxPoolSize' => 20, From 62442527111b61e414a6252ed85e1d2076dbdaa3 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 19 Apr 2024 12:31:33 -0400 Subject: [PATCH 10/15] grammar fixes --- docs/fundamentals/connection/connect-to-mongodb.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index d322c6a05..792a70aa0 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -112,8 +112,8 @@ For a MongoDB database connection, you can specify the following details: - ``options`` and ``driverOptions``, which specify connection options to pass to the MongoDB driver -The following example shows how you can specify a your MongoDB connection -details in a ``connections`` array entry: +The following example shows how you can specify your MongoDB connection details +in a ``connections`` array entry: .. code-block:: php :caption: Example config/database.php MongoDB connection configuration @@ -134,7 +134,7 @@ details in a ``connections`` array entry: // ... ], -The next sections provide common ways of specifying MongoDB connections. +The following sections provide common ways of specifying MongoDB connections. .. _laravel-atlas-connection-example: From afdf2c456f82b747f470f0457f4be667aa7867c2 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 19 Apr 2024 15:29:06 -0400 Subject: [PATCH 11/15] PRR fixes --- docs/fundamentals.txt | 2 +- docs/fundamentals/connection.txt | 4 +- .../connection/connect-to-mongodb.txt | 64 ++++++++++++++----- docs/index.txt | 1 + 4 files changed, 53 insertions(+), 18 deletions(-) diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index 9872a02fe..004930ad2 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -22,7 +22,7 @@ Fundamentals Learn how to use the {+odm-long+} to perform the following tasks: -- :ref:`Connections ` +- :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 index fab7e26af..e9f47f453 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -17,8 +17,8 @@ Connections 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 +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:`Connect to MongoDB ` diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 792a70aa0..8663fc948 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -87,10 +87,9 @@ Laravel Database Connection Configuration ``config/database.php`` Laravel application file. You can specify the following connection details in this file: -- ``default``, which specifies the default database connection to use when - unspecified +- ``default``, which specifies the database connection to use when unspecified - ``connections``, which contains database connection information to access - various databases from your application + 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: @@ -101,19 +100,54 @@ connection to a corresponding ``"mongodb"`` entry in the ``connections`` array: For a MongoDB database connection, you can specify the following details: -- ``driver``, which specifies the database driver to use for the connection -- ``dsn``, the data source name (DSN) that specifies the MongoDB connection URI -- ``host``, which you can use instead of the ``dsn`` setting to specify the - network address of one or more MongoDB nodes -- ``database``, which specifies the name of the MongoDB database to read and - write to -- ``username`` and ``password``, which you can optionally include to specify - your database user's credentials to authenticate with MongoDB -- ``options`` and ``driverOptions``, which specify connection options to - pass to the MongoDB driver +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 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 of one or more MongoDB nodes in a + deployment. You can use this setting instead of the ``dsn`` setting. + + * - ``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 a ``connections`` array entry: +in the ``connections`` array item: .. code-block:: php :caption: Example config/database.php MongoDB connection configuration @@ -201,7 +235,7 @@ 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. +- 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``. diff --git a/docs/index.txt b/docs/index.txt index 9f6b76483..12d1290c3 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -61,6 +61,7 @@ Fundamentals To learn how to perform the following tasks by using {+odm-short+}, see the following content: +- :ref:`Configure Your MongoDB Connection ` - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-eloquent-models` From 9304ac2073f08c91c51c9cd3aaea0ae94a4f83bd Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 19 Apr 2024 15:41:53 -0400 Subject: [PATCH 12/15] tweaks --- .../connection/connect-to-mongodb.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 8663fc948..5fd5b675d 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -102,39 +102,39 @@ For a MongoDB database connection, you can specify the following details: .. list-table:: :header-rows: 1 - :widths: 30 70 + :widths: 25 75 * - Setting - Description * - ``driver`` - - Specifies the database driver to use for the connection + - Specifies the database driver to use for the connection. * - ``dsn`` - - The data source name (DSN) that specifies the MongoDB connection URI + - The data source name (DSN) that specifies the MongoDB connection URI. * - ``host`` - Specifies the network address of one or more MongoDB nodes in a deployment. You can use this setting instead of the ``dsn`` setting. * - ``database`` - - Specifies the name of the MongoDB database to read and write to + - Specifies the name of the MongoDB database to read and write to. * - ``username`` - Specifies your database user's username credential to authenticate - with MongoDB + with MongoDB. * - ``password`` - Specifies your database user's password credential to authenticate - with MongoDB + with MongoDB. * - ``options`` - Specifies connection options to pass to MongoDB that determine the - connection behavior + connection behavior. * - ``driverOptions`` - Specifies options specific to pass to the MongoDB PHP Library driver - that determine the driver behavior for that connection + that determine the driver behavior for that connection. .. note:: From af097168d755fc5c61f9390c544947d60a7f5ba5 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 19 Apr 2024 16:33:00 -0400 Subject: [PATCH 13/15] PRR fixes --- docs/fundamentals/connection.txt | 2 +- docs/fundamentals/connection/connect-to-mongodb.txt | 6 +++--- docs/index.txt | 3 ++- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index e9f47f453..b1d11c58a 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -21,5 +21,5 @@ 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:`Connect to MongoDB ` +- :ref:`laravel-connect-to-mongodb` diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 5fd5b675d..13de9ac0e 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -92,7 +92,7 @@ connection details in this file: 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: +connection to a corresponding ``mongodb`` entry in the ``connections`` array: .. code-block:: php @@ -190,10 +190,10 @@ To add your MongoDB DSN to your Laravel application, make the following changes: 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:: php +.. code-block:: bash :caption: Sample .env environment configuration - DB_URI=""mongodb+srv://myUser:myPass123@mongodb0.example.com/"; + DB_URI="mongodb+srv://myUser:myPass123@mongodb0.example.com/" .. code-block:: php :caption: Sample config/database.php connection entry diff --git a/docs/index.txt b/docs/index.txt index 12d1290c3..38ceb7a89 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:`Configure Your MongoDB Connection ` +- :ref:laravel-fundamentals-connection` +- :ref:laravel-db-coll` - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-eloquent-models` From c7d4f462e968aa36314bca867b380e0211f88b58 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 22 Apr 2024 12:15:09 -0400 Subject: [PATCH 14/15] PRR fixes --- .../connection/connect-to-mongodb.txt | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 13de9ac0e..7de96ad76 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -114,8 +114,29 @@ For a MongoDB database connection, you can specify the following details: - The data source name (DSN) that specifies the MongoDB connection URI. * - ``host`` - - Specifies the network address of one or more MongoDB nodes in a - deployment. You can use this setting instead of the ``dsn`` setting. + - | 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. From 2b3b6613752e45f8bb98d07f0db75968c36d1784 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 22 Apr 2024 12:26:05 -0400 Subject: [PATCH 15/15] rst fix --- docs/index.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.txt b/docs/index.txt index f0d72cd1e..88aee9d65 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -61,8 +61,8 @@ Fundamentals To learn how to perform the following tasks by using {+odm-short+}, see the following content: -- :ref:laravel-fundamentals-connection` -- :ref:laravel-db-coll` +- :ref:`laravel-fundamentals-connection` +- :ref:`laravel-db-coll` - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-eloquent-models`