DOCSP-35938: Connection Guide docs #2881

ccho-mongodb · 2024-04-18T22:24:50Z

JIRA: https://jira.mongodb.org/browse/DOCSP-35938

Checklist

Add tests and ensure they pass
Add an entry to the CHANGELOG.md file
Update documentation for new features

ccho-mongodb · 2024-04-18T22:36:07Z

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

+
+- ``maxPoolSize=20``
+- ``w=majority``
+


Note:
This section will include a link to the Connection Options page once completed.

GromNaN · 2024-04-19T08:02:12Z

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

+
+.. code-block:: bash
+
+   DB_URI="mongodb://myUser:myPass123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS"


After testing on a local replica set, I can confirm that the replicatSet option works.

MONGODB_URI="mongodb://localhost:27017,localhost:27018,localhost:27019/"

'mongodb' => [ 'driver' => 'mongodb', 'dsn' => env('MONGODB_URI'), 'database' => 'laravel', 'options' => [ 'replicaSet' => 'myRS', ] ]

You can also pass the list of hosts like this:

'mongodb' => [ 'driver' => 'mongodb', 'host' => [ '127.0.0.1:27017', '127.0.0.1:27018', '127.0.0.1:27019', ], 'database' => 'laravel', 'options' => [ 'replicaSet' => 'myRS', ] ]

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

rustagir

a few things!

rustagir · 2024-04-19T17:46:18Z

docs/fundamentals.txt

   /fundamentals/database-collection
   /fundamentals/read-operations
   /fundamentals/write-operations

 Learn how to use the {+odm-long+} to perform the following tasks:

- :ref:`Manage Databases and Collections <laravel-db-coll>`
+- :ref:`Connections <laravel-fundamentals-connection>`


S: though Connections is the name of the page, perhaps this link text could be more matched to the intro phrase "perform the following tasks"

Suggested change

- :ref:`Connections <laravel-fundamentals-connection>`

- :ref:`Configure Your Connection to MongoDB <laravel-fundamentals-connection>`

I'll add an item to the cleanup ticket to address the other titles that aren't action oriented.

rustagir · 2024-04-19T18:13:51Z

docs/fundamentals.txt

   /fundamentals/database-collection
   /fundamentals/read-operations
   /fundamentals/write-operations

 Learn how to use the {+odm-long+} to perform the following tasks:

- :ref:`Manage Databases and Collections <laravel-db-coll>`
+- :ref:`Connections <laravel-fundamentals-connection>`


S: also add this to the list of fundamentals pages on the index (alternatively, move into an include that is used on both pages)

Adding the item to index.txt and then adding the task to move it into an include to the cleanup ticket since it impacts other content.

rustagir · 2024-04-19T18:14:52Z

docs/fundamentals/connection.txt

+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:


Suggested change

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:

Learn how to set up a connection from your Laravel application to a MongoDB

deployment and specify connection behavior by using {+odm-short+} in the

following sections:

rustagir · 2024-04-19T18:15:15Z

docs/fundamentals/connection.txt

+Laravel application to a MongoDB deployment by using {+odm-short+} in the
+following sections:
+
+- :ref:`Connect to MongoDB <laravel-connect-to-mongodb>`


q: why is this called connect to MongoDB instead of Connection Guide?

This was a custom title with similar intent to the suggestions you made earlier. To keep it simple, I'd suggest that we only use the titles of the pages and then describe them as necessary. Let me know what you think and I'll add the appropriate task to the cleanup ticket.

This sounds like a good solution to prevent the same page from being referred to by different things in different places!

Great, added "Use the original titles for all landing page link lists. Use a description if it needs additional explanation." to the cleanup ticket.

rustagir · 2024-04-19T18:20:31Z

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

+- ``default``, which specifies the default database connection to use when
+  unspecified


Suggested change

- ``default``, which specifies the default database connection to use when

unspecified

- ``default``, which specifies the default database connection to use

Thanks for the suggestion. I wanted to emphasize the behavior of the default value, but now think maybe including "default" in the description of itself might be confusing. think maybe a more clear way to describe this could be:
"default, which specifies the database connection to use when unspecified"

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

rustagir · 2024-04-19T18:21:34Z

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

+- ``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


S: maybe converting this into a table could be helpful

rustagir · 2024-04-19T18:22:28Z

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

+- ``options`` and ``driverOptions``, which specify connection options to
+  pass to the MongoDB driver


Q: is there a place to find a complete list of what goes under each property? Or will this be covered in the connection options page

Thanks for asking. These are covered in the Connection Options ticket and a link will be added to this page per #2881 (comment)

rustagir · 2024-04-19T18:23:45Z

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

+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.


Suggested change

- Download, install, and run MongoDB server.

- Download, install, and run the MongoDB server.

rustagir · 2024-04-19T18:25:01Z

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

+- ``username`` and ``password``, which you can optionally include to specify
+  your database user's credentials to authenticate with MongoDB


I: right now, it's not very clear that using different properties such as host username password port, etc. is an alternative to including all of this information in the DSN

S: add an admonition or revise these descriptions to make this clear

Good idea! Will add an admonition to explain.

rustagir

lgtm!

rustagir · 2024-04-19T19:44:24Z

docs/fundamentals/connection.txt

+Laravel application to a MongoDB deployment by using {+odm-short+} in the
+following sections:
+
+- :ref:`Connect to MongoDB <laravel-connect-to-mongodb>`


This sounds like a good solution to prevent the same page from being referred to by different things in different places!

rustagir · 2024-04-19T19:46:10Z

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

+  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:


Suggested change

connection to a corresponding ``"mongodb"`` entry in the ``connections`` array:

connection to a corresponding ``mongodb`` entry in the ``connections`` array:

rustagir · 2024-04-19T19:47:01Z

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

+.. code-block:: php
+   :caption: Sample .env environment configuration
+
+   DB_URI=""mongodb+srv://myUser:[email protected]/";


Suggested change

DB_URI=""mongodb+srv://myUser:[email protected]/";

DB_URI="mongodb+srv://myUser:[email protected]/"

Whoops, great catch!
I should also use "bash" instead of "php" highlighting.

GromNaN · 2024-04-22T15:26:35Z

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

+   * - ``host``
+     - Specifies the network address of one or more MongoDB nodes in a
+       deployment. You can use this setting instead of the ``dsn`` setting.


This is host:port or a list of host:port.

Examples:

'host' => 'localhost:27017'

'host' => ['server1.example.net:27017', 'server2.example.net:27017', 'server3.example.net:27017']

Question: from my experimentation, this option only accepts non-seedlist hostnames (mongodb and not mongodb+srv), correct?

In fact, we need to add an option for mongodb+srv.

laravel-mongodb/src/Connection.php

Line 255 in d0978a8

return 'mongodb://' . implode(',', $hosts) . ($authDatabase ? '/' . $authDatabase : '');

GromNaN · 2024-04-22T15:29:07Z

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

+   * - ``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.


You should link to the doc of options: https://www.mongodb.com/docs/php-library/current/reference/method/MongoDBClient__construct/#parameters

Thanks, I will add links from options and driverOptions to the Connection Options page (which includes the link you provided) once merged as a cleanup task.

Chris Cho added 6 commits April 18, 2024 09:39

DOCSP-35938: Connect to MongoDB

49c65b1

rework examples

f3f89c7

RST fixes

06b7b21

rename

ef9809f

grammar fixes

224e925

tweaks

abcc44a

ccho-mongodb changed the title ~~Docsp 35938 connect to mongodb~~ DOCSP-35938: Connection Guide docs Apr 18, 2024

ccho-mongodb added the docs label Apr 18, 2024

ccho-mongodb commented Apr 18, 2024

View reviewed changes

GromNaN self-requested a review April 19, 2024 07:51

GromNaN reviewed Apr 19, 2024

View reviewed changes

Chris Cho added 4 commits April 19, 2024 12:10

add section on the database config file

b78f5fe

fixes

80ddf48

update example password

29eb1dd

grammar fixes

6244252

rustagir requested changes Apr 19, 2024

View reviewed changes

Chris Cho added 2 commits April 19, 2024 15:29

PRR fixes

afdf2c4

tweaks

9304ac2

rustagir approved these changes Apr 19, 2024

View reviewed changes

Chris Cho and others added 2 commits April 19, 2024 16:33

PRR fixes

af09716

Merge branch '4.1' into DOCSP-35938-connect-to-mongodb

19bc198

ccho-mongodb assigned GromNaN Apr 19, 2024

ccho-mongodb marked this pull request as ready for review April 19, 2024 20:35

ccho-mongodb requested a review from a team as a code owner April 19, 2024 20:35

ccho-mongodb requested a review from GromNaN April 19, 2024 20:35

GromNaN reviewed Apr 22, 2024

View reviewed changes

Chris Cho added 2 commits April 22, 2024 12:15

PRR fixes

c7d4f46

rst fix

2b3b661

ccho-mongodb requested a review from GromNaN April 22, 2024 16:36

GromNaN approved these changes Apr 22, 2024

View reviewed changes

ccho-mongodb merged commit 19bb87f into mongodb:4.1 Apr 22, 2024

ccho-mongodb deleted the DOCSP-35938-connect-to-mongodb branch April 22, 2024 17:18

This was referenced Apr 22, 2024

Merge 4.1 into 4.2 #2893

Merged

Merge 4.1 into 4.2 #2895

Merged

Merge 4.2 into 4.3 #2896

Merged


		.. code-block:: bash

		DB_URI="mongodb://myUser:myPass123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS"

	- :ref:`Connections <laravel-fundamentals-connection>`
	- :ref:`Configure Your Connection to MongoDB <laravel-fundamentals-connection>`

		- ``default``, which specifies the default database connection to use when
		unspecified

		- ``options`` and ``driverOptions``, which specify connection options to
		pass to the MongoDB driver

	- Download, install, and run MongoDB server.
	- Download, install, and run the MongoDB server.

		- ``username`` and ``password``, which you can optionally include to specify
		your database user's credentials to authenticate with MongoDB

	connection to a corresponding ``"mongodb"`` entry in the ``connections`` array:
	connection to a corresponding ``mongodb`` entry in the ``connections`` array:

	DB_URI=""mongodb+srv://myUser:[email protected]/";
	DB_URI="mongodb+srv://myUser:[email protected]/"

DOCSP-35938: Connection Guide docs #2881

DOCSP-35938: Connection Guide docs #2881

Uh oh!

Conversation

ccho-mongodb commented Apr 18, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccho-mongodb Apr 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccho-mongodb Apr 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ccho-mongodb commented Apr 18, 2024 •

edited

Loading

ccho-mongodb Apr 19, 2024 •

edited

Loading

ccho-mongodb Apr 22, 2024 •

edited

Loading