DOCSP-46328: Django connection configuration

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"
 language = "Python"
 mdb-server = "MongoDB Server"
 mongo-community = "MongoDB Community Edition"

source/configure-connection.txt

@@ -0,0 +1,175 @@
+.. _django-connection-configuration:
+
+==================================
+Configure Your Database Connection
+==================================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connection string, URI, server, settings
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to connect your Django project to MongoDB
+and configure the connection.
+
+Connection Configuration 
+------------------------
+
+After installing {+django-odm+} and creating a project, you can configure
+your connection to MongoDB in the following ways:
+
+- :ref:`django-connection-configure-manual` by specifying the
+  ``DATABASES`` variable in your project's settings
+- :ref:`django-connection-configure-automatic` by using
+  the ``parse_uri()`` method
+
+.. tip::
+
+   To learn how to install the Django ODM and create a
+   Django project, visit the :ref:`django-get-started` tutorial.
+
+.. _django-connection-configure-manual:
+
+Manually Configure Database Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Key
+     - Description
+
+   * - **ENGINE**
+     - The backend driver to use for the connection. Set this key to ``"django_mongodb_backend"``.
+
+   * - **HOST**
+     - | Your connection URI. For localhost connections, this key is optional. 
+       | For SRV connections, you must include a scheme prefix (``mongodb+srv://``).
+       |
+       | If connecting to a replica set or sharded cluster with multiple hosts, specify 
+       | each host separated by a comma.
+
+   * - **NAME**
+     - The database you want to use.
+
+   * - **USER**
+     - The username for authenticating to the database.
+
+   * - **PASSWORD**
+     - The password for your database user.
+
+   * - **PORT**
+     - | The port number on which the database server is listening. 
+       | For MongoDB Atlas connections, this key is optional.
+
+   * - **OPTIONS**
+     - A dictionary of additional connection options for the database. This key is optional.
+
+.. _django-manual-config-example:
+
+Example 
+```````
+
+This example specifies the ``DATABASES`` variable to connect
+to a MongoDB deployment with the following configuration:
+
+- Connects to the ``my_database`` database
+- Provides authentication information for a database user
+  whose username is ``my_user`` and password is ``my_password``
+- Uses the default MongoDB port (``27017``)
+- Sets the ``retryWrites`` connection option to ``true``,
+  which configures the driver to automatically retry certain
+  write operations if they fail
+- Sets the ``w`` connection option to ``majority``,
+  which configures the driver to wait for acknowledgement from a majority
+  of replica set members before performing write operations
+
+.. code-block:: python
+
+    DATABASES = {
+        "default": {
+            "ENGINE": "django_mongodb_backend",
+            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
+            "NAME": "my_database",
+            "USER": "my_user",
+            "PASSWORD": "my_password",
+            "PORT": 27017,
+            "OPTIONS": {
+                "retryWrites": "true",
+                "w": "majority",
+            },
+        },
+    }
+
+.. tip::
+
+    To see a full list of connection options that you
+    can set in the ``OPTIONS`` key, see the optional
+    parameters for `MongoClient <https://pymongo.readthedocs.io/en/4.10.1/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
+    in the PyMongo API documentation.
+
+.. _django-connection-configure-automatic:
+
+Automatically Configure Database Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To automatically construct the ``DATABASES`` setting that configures
+your MongoDB connection, you can use the ``parse_uri()`` method. This
+method accepts the following arguments:
+
+- ``uri``: Your MongoDB connection URI.
+- ``conn_max_age``: Configures persistent database connections.
+  This argument is optional. To learn more, see 
+  `Persistent connections <https://docs.djangoproject.com/en/stable/ref/databases/#persistent-database-connections>`__
+  in the Django documentation.
+- ``test``: Provides a dictionary of settings for test
+  databases. This argument is optional. To learn more, see 
+  `the TEST setting <https://docs.djangoproject.com/en/stable/ref/settings/#test>`__
+  in the Django documentation.
+
+Example 
+```````
+
+The following example uses the ``parse_uri()`` method to connect
+to a MongoDB deployment with the same configuration as 
+the previous :ref:`manual configuration <django-manual-config-example>`
+example:
+
+.. code-block:: python
+
+    import django_mongodb_backend
+
+    MONGODB_URI = "mongodb+srv://my_user:[email protected]/my_database?retryWrites=true&w=majority"
+    DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI)
+
+Additional Information
+----------------------
+
+To view a sample project that configures a MongoDB database connection,
+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/>`__
+in the Django documentation.