DOCSP-46328: Django connection configuration #142

norareidy · 2025-01-08T21:53:45Z

Pull Request Info

PR Reviewing Guidelines
Note: This PR will move to the docs-django repo once it's created

JIRA - https://jira.mongodb.org/browse/DOCSP-46328
Staging - https://deploy-preview-142--docs-pymongo.netlify.app/configure-connection/

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

netlify · 2025-01-08T22:00:32Z

✅ Deploy Preview for docs-pymongo ready!

Name	Link
🔨 Latest commit	`90b7c58`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-pymongo/deploys/67868e2b60f41f0008361a1d
😎 Deploy Preview	https://deploy-preview-142--docs-pymongo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

norareidy · 2025-01-08T22:38:57Z

source/configure-connection.txt

+.. tip::
+
+   To learn how to install the Django ODM and create a
+   Django project, visit the :ref:`django-get-started` tutorial.


Note: this link is broken until #132 is merged

norareidy · 2025-01-08T22:39:25Z

source/configure-connection.txt

+connection.
+
+To configure the ``default`` key, include the following
+fields:


Note to tech reviewers: not sure if "field" is the right word here? are these also keys?

Yes DATABASES is a nested dictionary of settings so you might say

To configure the default key, include the following nested keys.

Or

To configure the default key, include the following settings.

Or

To configure the default database, include the following settings.

But you probably wouldn't say "fields".

aclark4life · 2025-01-10T13:04:40Z

source/configure-connection.txt

@@ -125,7 +125,7 @@ to a MongoDB deployment with the following configuration:
 .. tip::

    To see a full list of connection options that you
-    can set in the ``OPTIONS`` field, see the optional
+    can set in the ``OPTIONS`` nested key, see the optional


s/key/dictionary/, otherwise, nice!

aclark4life

LGTM!

aclark4life · 2025-01-10T13:09:08Z

source/configure-connection.txt

@@ -51,20 +51,20 @@ which you must configure to set MongoDB as the default database
 connection.

 To configure the ``default`` key, include the following
-fields:
+nested keys:


To configure the default database, include the following nested dictionary.

Jibola

Overall looks good. I've got two minor changes and that's it!

Jibola · 2025-01-10T20:34:03Z

source/configure-connection.txt

+     - The database you want to use.
+
+   * - **USER**
+     - The username for authenticating to the database.


You can add if your connection requires no auth you do not need to provide it

Jibola · 2025-01-10T20:34:47Z

source/configure-connection.txt

+   * - **PASSWORD**
+     - The password for your database user.
+
+   * - **PORT**


Here you can say the default port is 27017

Jibola · 2025-01-10T20:40:26Z

source/configure-connection.txt

+see the :ref:`django-get-started-connect` step in the Getting Started
+tutorial.
+
+To learn more about Django settings, see `Settings <https://docs.djangoproject.com/en/stable/ref/settings/>`__


NIT for future version mappings. We will need to have the links point to the correlating version. Right now it points to stable

mongoKart

really nice. a few small wording suggestions and questions

source/configure-connection.txt

mongoKart · 2025-01-13T17:53:45Z

source/configure-connection.txt

+To manually configure your connection to MongoDB, update
+the ``DATABASES`` variable in your project's ``settings.py``
+file. Set the ``DATABASES`` variable to a dictionary value containing
+the database settings. You must configure the dictionary's
+``default`` key to set MongoDB as the default database
+connection.
+
+To configure the ``default`` key, assign a nested dictionary as its value.
+This nested dictionary has the following keys:


s: i had a hard time understanding this paragraph until i scrolled down to the code example. what do you think about starting with a code example (maybe without any options in it), then going to the table that explains each option, then a fully fleshed out code example?

Suggested change

To manually configure your connection to MongoDB, update

the ``DATABASES`` variable in your project's ``settings.py``

file. Set the ``DATABASES`` variable to a dictionary value containing

the database settings. You must configure the dictionary's

``default`` key to set MongoDB as the default database

connection.

To configure the ``default`` key, assign a nested dictionary as its value.

This nested dictionary has the following keys:

To manually configure your connection to MongoDB, update

the ``DATABASES`` variable in your project's ``settings.py``

file. Set the ``DATABASES`` variable to a dictionary value containing

a key named ``default``, as shown in the following example:

.. code-block:: python

DATABASES = {

"default": {

},

}

Set the ``default`` key to a dictionary that contains the following keys:

That makes sense, reworked this part!

mongoKart · 2025-01-13T18:03:46Z

source/configure-connection.txt

+       | If connecting to a replica set or sharded cluster with multiple hosts, specify 
+       | each host separated by a comma.


s: slight wording suggestion. could also be helpful to include an example, either here or later.

Suggested change

| If connecting to a replica set or sharded cluster with multiple hosts, specify

| each host separated by a comma.

| To specify more than one host, include all hostnames in one string. Use

| a comma to separate each hostname.

mongoKart · 2025-01-13T18:08:43Z

source/configure-connection.txt

+This example specifies the ``DATABASES`` variable to connect
+to a MongoDB deployment with the following configuration:


s:

Suggested change

This example specifies the ``DATABASES`` variable to connect

to a MongoDB deployment with the following configuration:

In this example, the ``DATABASES`` variable specifies the

following connection configuration:

mongoKart · 2025-01-13T18:10:52Z

source/configure-connection.txt

+This example specifies the ``DATABASES`` variable to connect
+to a MongoDB deployment with the following configuration:
+
+- Connects to the ``my_database`` database


q: related to the preceding paragraph: who is the actor in the list? the client, DATABASES, the
connection, the deployment, the app, or something else? It seems to mix client/app behavior ('Connects to the database' with config behavior ('Sets the connection option...')

I was thinking DATABASES. I'll change some of the wording

Wow, English discussion going on here. I would say s/variable to connect to/variable used to connect to/ and reserve further English language usage comments. 😄

mongoKart · 2025-01-13T18:11:27Z

source/configure-connection.txt

+        },
+    }
+
+.. tip::


s: move this to the OPTIONS row above (and take out of tip box to avoid nested admonition)

mongoKart · 2025-01-13T18:12:20Z

source/configure-connection.txt

+Automatically Configure Database Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To automatically construct the ``DATABASES`` setting that configures


q: does this literally construct the DATABASES variable in that file with that same structure? or does it just have the same effect on the client/connection?

The Django MongoDB README says it "constructs a DATABASES setting equivalent to the first example" -- @Jibola is it accurate to say that parse_uri() automatically constructs this setting?

parse_uri is a convenience method so if it helps to leave it out for clarity's sake then I would do that. That said, DATABASES has to exist and it has to have the required keys. For example, I can run Django without that setting but if I try to access the admin I get

settings.DATABASES is improperly configured. Please supply the ENGINE value. Check settings documentation for more details.

Also FWIW my preference for testing is currently: https://github.com/aclark4life/project-templates/blob/main/project_template/project_name/settings/__init__.py#L7 with MONGODB_URI set by direnv.

And finally, please note we currently use parse_uri in the project template.

It seems accurate to say it's constructing the DATABASES setting, so I'll leave that in.
Since I'm showing how to configure the same settings as the previous example, I'll leave the MONGODB_URI variable that shows how to do that

mongoKart · 2025-01-13T18:13:06Z

source/configure-connection.txt

+The following example uses the ``parse_uri()`` method to connect
+to a MongoDB deployment with the same configuration as 


s:

Suggested change

The following example uses the ``parse_uri()`` method to connect

to a MongoDB deployment with the same configuration as

The following example uses the ``parse_uri()`` method to specify

the same connection configuration as

NIT: s/method/function/

mongoKart

lgtm w/ 1 wording change. let me know if you want to brainstorm ideas

mongoKart · 2025-01-13T20:52:41Z

source/configure-connection.txt

+In this example, the ``DATABASES`` variable specifies the
+following connection configuration:

- Connects to the ``my_database`` database
+- Sets the database to ``my_database``
 - Provides authentication information for a database user
  whose username is ``my_user`` and password is ``my_password``
- Uses the default MongoDB port (``27017``)
+- Specifies the default MongoDB port (``27017``)
 - Sets the ``retryWrites`` connection option to ``true``,


i: there's a double verb here--'specifies' in the paragraph and then 'connects'/'sets' in the list items. i can't add a suggestion in GH, but maybe something like this:

In this example, the DATABASES variable performs the
following steps:

changed to just "...performs the following actions"

aclark4life · 2025-01-13T22:42:40Z

snooty.toml

@@ -25,6 +25,7 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 driver-short = "PyMongo"
 driver-long = "PyMongo, the MongoDB synchronous Python driver,"
 driver-async = "PyMongo Async"
+django-odm = "MongoDB Backend for Django"


Can this be "Django MongoDB Backend" or are we required to say "MongoDB Backend for Django" ?

I can change it! updated

aclark4life · 2025-01-13T22:44:03Z

source/configure-connection.txt

+--------
+
+In this guide, you can learn how to connect your Django project to MongoDB
+and configure the connection.


FWIW this still reads "funny" to me … if you are connecting your Django project to MongoDB then you've already configured the connection. Feel free to override me because I can be NIT-happy.

aclark4life · 2025-01-13T22:45:29Z

source/configure-connection.txt

+
+.. tip::
+
+   To learn how to install the Django ODM and create a


Should this be {+django-odm+} instead of "Django ODM" ?

norareidy · 2025-01-16T17:15:13Z

Moved to the Django repo: mongodb/docs-django#6

norareidy added 2 commits January 8, 2025 16:53

DOCSP-46328: Connection configuration

e35be75

edits

445573a

fixes

49b6d69

norareidy commented Jan 8, 2025

View reviewed changes

norareidy requested review from aclark4life, Jibola and R-shubham January 8, 2025 22:39

field->key

5500f74

aclark4life reviewed Jan 10, 2025

View reviewed changes

wording edits

9a9220b

aclark4life approved these changes Jan 10, 2025

View reviewed changes

Jibola suggested changes Jan 10, 2025

View reviewed changes

mongoKart requested changes Jan 13, 2025

View reviewed changes

norareidy added 2 commits January 13, 2025 15:36

feedback

3b69e3e

fixes

f935192

norareidy requested review from mongoKart and Jibola January 13, 2025 20:47

mongoKart approved these changes Jan 13, 2025

View reviewed changes

MW feedback 2

1049049

aclark4life reviewed Jan 13, 2025

View reviewed changes

norareidy added 2 commits January 14, 2025 10:50

AC feedback 2

11d4f2c

fix

90b7c58

Jibola approved these changes Jan 16, 2025

View reviewed changes

norareidy closed this Jan 16, 2025

norareidy mentioned this pull request Jan 16, 2025

DOCSP-46328: Connection configuration mongodb/docs-django#6

Merged

5 tasks

		\| If connecting to a replica set or sharded cluster with multiple hosts, specify
		\| each host separated by a comma.

		This example specifies the ``DATABASES`` variable to connect
		to a MongoDB deployment with the following configuration:

		The following example uses the ``parse_uri()`` method to connect
		to a MongoDB deployment with the same configuration as

DOCSP-46328: Django connection configuration #142

DOCSP-46328: Django connection configuration #142

Uh oh!

Conversation

norareidy commented Jan 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Self-Review Checklist

Uh oh!

netlify bot commented Jan 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-pymongo ready!

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!

aclark4life left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jibola 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!

mongoKart left a comment

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!

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!

aclark4life Jan 13, 2025 • 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!

aclark4life Jan 13, 2025 • 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!

mongoKart 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!

norareidy commented Jan 8, 2025 •

edited

Loading

netlify bot commented Jan 8, 2025 •

edited

Loading

aclark4life Jan 13, 2025 •

edited

Loading

aclark4life Jan 13, 2025 •

edited

Loading

aclark4life Jan 13, 2025 •

edited

Loading