From e35be750beaf07709554893474b0207e9c054f2e Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 8 Jan 2025 16:53:07 -0500 Subject: [PATCH 01/10] DOCSP-46328: Connection configuration --- source/configure-connection.txt | 163 ++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 source/configure-connection.txt diff --git a/source/configure-connection.txt b/source/configure-connection.txt new file mode 100644 index 00000000..4e78797e --- /dev/null +++ b/source/configure-connection.txt @@ -0,0 +1,163 @@ +.. _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 updating the + ``DATABASES`` setting +- :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`` setting in your project's ``settings.py`` +file. The ``DATABASES`` setting has a ``default`` key, +which you must specify to set MongoDB as the default database +connection. + +To specify the ``default`` key, include the following +information: + +- ``ENGINE``: The backend driver to use for the connection. + Set this field to ``"django_mongodb_backend"``. + +- ``HOST``: Your connection URI. For localhost connections, + this field 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 field is optional. + +- ``OPTIONS``: A dictionary of additional connection options for the database. + This field is optional. + +.. _django-manual-config-example: + +Example +``````` + +This example specifies the ``DATABASES`` setting to connect +to a MongoDB deployment with the following configuration: + +- Connects to the ``sample_db`` database +- Provides authentication information for a 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 pass to the ``OPTIONS`` field, see the optional + parameters for `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 parameters: + +- ``uri``: Your MongoDB connection URI. +- ``conn_max_age``: Configures persistent database connections. + This parameter is optional. To learn more, see + `Persistent connections `__ + in the Django documentation. +- ``test``: Provides a dictionary of settings for test + databases. This parameter is optional. To learn more, see + `the TEST setting `__ + 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 :ref:`manual configuration ` +example in this guide: + +.. code-block:: python + + import django_mongodb_backend + + MONGODB_URI = "mongodb+srv://my_user:my_password@cluster0.example.mongodb.net/myDatabase?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 `__ +in the Django documentation. \ No newline at end of file From 445573a699d07dafc8af71743b9ad9649d459eef Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 8 Jan 2025 17:00:03 -0500 Subject: [PATCH 02/10] edits --- source/configure-connection.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/configure-connection.txt b/source/configure-connection.txt index 4e78797e..9f7a56ee 100644 --- a/source/configure-connection.txt +++ b/source/configure-connection.txt @@ -29,8 +29,8 @@ 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 updating the - ``DATABASES`` setting +- :ref:`django-connection-configure-manual` by updating your + project's ``DATABASES`` setting - :ref:`django-connection-configure-automatic` by using the ``parse_uri()`` method @@ -114,7 +114,7 @@ to a MongoDB deployment with the following configuration: .. tip:: To see a full list of connection options that you - can pass to the ``OPTIONS`` field, see the optional + can set in the ``OPTIONS`` field, see the optional parameters for `MongoClient `__ in the PyMongo API documentation. @@ -142,8 +142,8 @@ Example The following example uses the ``parse_uri()`` method to connect to a MongoDB deployment with the same configuration as -the :ref:`manual configuration ` -example in this guide: +the previous :ref:`manual configuration ` +example: .. code-block:: python From 49b6d69e7370ec775cba979d2a7144793c8c1f4a Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 8 Jan 2025 17:34:00 -0500 Subject: [PATCH 03/10] fixes --- snooty.toml | 1 + source/configure-connection.txt | 57 ++++++++++++++++++++------------- 2 files changed, 35 insertions(+), 23 deletions(-) diff --git a/snooty.toml b/snooty.toml index de16c44e..eead367f 100644 --- a/snooty.toml +++ b/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" diff --git a/source/configure-connection.txt b/source/configure-connection.txt index 9f7a56ee..19597ae0 100644 --- a/source/configure-connection.txt +++ b/source/configure-connection.txt @@ -47,33 +47,44 @@ Manually Configure Database Settings To manually configure your connection to MongoDB, update the ``DATABASES`` setting in your project's ``settings.py`` file. The ``DATABASES`` setting has a ``default`` key, -which you must specify to set MongoDB as the default database +which you must configure to set MongoDB as the default database connection. -To specify the ``default`` key, include the following -information: +To configure the ``default`` key, include the following +fields: -- ``ENGINE``: The backend driver to use for the connection. - Set this field to ``"django_mongodb_backend"``. +.. list-table:: + :header-rows: 1 + :widths: 20 80 -- ``HOST``: Your connection URI. For localhost connections, - this field is optional. For SRV connections, you must include - a scheme prefix (``mongodb+srv://``). + * - Field + - Description - If connecting to a replica set or sharded cluster with multiple hosts, specify - each host separated by a comma. + * - **ENGINE** + - The backend driver to use for the connection. Set this field to ``"django_mongodb_backend"``. -- ``NAME``: The database you want to use. + * - **HOST** + - | Your connection URI. For localhost connections, this field 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. -- ``USER``: The username for authenticating to the database. + * - **NAME** + - The database you want to use. -- ``PASSWORD``: The password for your database user. + * - **USER** + - The username for authenticating to the database. -- ``PORT``: The port number on which the database server is listening. - For MongoDB Atlas connections, this field is optional. + * - **PASSWORD** + - The password for your database user. -- ``OPTIONS``: A dictionary of additional connection options for the database. - This field is optional. + * - **PORT** + - | The port number on which the database server is listening. + | For MongoDB Atlas connections, this field is optional. + + * - **OPTIONS** + - A dictionary of additional connection options for the database. This field is optional. .. _django-manual-config-example: @@ -83,8 +94,8 @@ Example This example specifies the ``DATABASES`` setting to connect to a MongoDB deployment with the following configuration: -- Connects to the ``sample_db`` database -- Provides authentication information for a user +- 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``, @@ -125,15 +136,15 @@ 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 parameters: +method accepts the following arguments: - ``uri``: Your MongoDB connection URI. - ``conn_max_age``: Configures persistent database connections. - This parameter is optional. To learn more, see + This argument is optional. To learn more, see `Persistent connections `__ in the Django documentation. - ``test``: Provides a dictionary of settings for test - databases. This parameter is optional. To learn more, see + databases. This argument is optional. To learn more, see `the TEST setting `__ in the Django documentation. @@ -149,7 +160,7 @@ example: import django_mongodb_backend - MONGODB_URI = "mongodb+srv://my_user:my_password@cluster0.example.mongodb.net/myDatabase?retryWrites=true&w=majority" + MONGODB_URI = "mongodb+srv://my_user:my_password@cluster0.example.mongodb.net/my_database?retryWrites=true&w=majority" DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI) Additional Information From 5500f740ce3440c3b3726249f492ca17dea8c03a Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 9 Jan 2025 17:35:13 -0500 Subject: [PATCH 04/10] field->key --- source/configure-connection.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/configure-connection.txt b/source/configure-connection.txt index 19597ae0..2601cf57 100644 --- a/source/configure-connection.txt +++ b/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: .. list-table:: :header-rows: 1 :widths: 20 80 - * - Field + * - Key - Description * - **ENGINE** - - The backend driver to use for the connection. Set this field to ``"django_mongodb_backend"``. + - The backend driver to use for the connection. Set this key to ``"django_mongodb_backend"``. * - **HOST** - - | Your connection URI. For localhost connections, this field is optional. + - | 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 @@ -81,10 +81,10 @@ fields: * - **PORT** - | The port number on which the database server is listening. - | For MongoDB Atlas connections, this field is optional. + | For MongoDB Atlas connections, this key is optional. * - **OPTIONS** - - A dictionary of additional connection options for the database. This field is optional. + - A dictionary of additional connection options for the database. This key is optional. .. _django-manual-config-example: @@ -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 parameters for `MongoClient `__ in the PyMongo API documentation. From 9a9220b7d3512d617ef605cea25d03e217966d48 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 10 Jan 2025 10:01:15 -0500 Subject: [PATCH 05/10] wording edits --- source/configure-connection.txt | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/source/configure-connection.txt b/source/configure-connection.txt index 2601cf57..80b05daf 100644 --- a/source/configure-connection.txt +++ b/source/configure-connection.txt @@ -29,8 +29,8 @@ 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 updating your - project's ``DATABASES`` setting +- :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 @@ -45,13 +45,14 @@ Manually Configure Database Settings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To manually configure your connection to MongoDB, update -the ``DATABASES`` setting in your project's ``settings.py`` -file. The ``DATABASES`` setting has a ``default`` key, -which you must configure to set MongoDB as the default database +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, include the following -nested keys: +To configure the ``default`` key, assign a nested dictionary as its value. +This nested dictionary has the following keys: .. list-table:: :header-rows: 1 @@ -91,7 +92,7 @@ nested keys: Example ``````` -This example specifies the ``DATABASES`` setting to connect +This example specifies the ``DATABASES`` variable to connect to a MongoDB deployment with the following configuration: - Connects to the ``my_database`` database @@ -125,7 +126,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`` nested key, see the optional + can set in the ``OPTIONS`` key, see the optional parameters for `MongoClient `__ in the PyMongo API documentation. From 3b69e3ea88f3f6d5d99cdf5e4247447131d29f5d Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 13 Jan 2025 15:36:59 -0500 Subject: [PATCH 06/10] feedback --- source/configure-connection.txt | 57 ++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/source/configure-connection.txt b/source/configure-connection.txt index 80b05daf..f28b869e 100644 --- a/source/configure-connection.txt +++ b/source/configure-connection.txt @@ -30,9 +30,9 @@ 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 + ``DATABASES`` variable in your project's settings. - :ref:`django-connection-configure-automatic` by using - the ``parse_uri()`` method + the ``parse_uri()`` method. .. tip:: @@ -47,9 +47,15 @@ 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. +the ``default`` key, as shown in the following example: + +.. code-block:: python + + DATABASES = { + "default": { + # Specify nested dictionary keys here + }, + } To configure the ``default`` key, assign a nested dictionary as its value. This nested dictionary has the following keys: @@ -68,37 +74,46 @@ This nested dictionary has the following keys: - | 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. + | To specify more than one host, include all hostnames in one string. Use + | a comma to separate each hostname, as shown in the following example: + + .. code-block:: python + + "HOST": "mongodb://mongos0.example.com:27017,mongos1.example.com:27017" * - **NAME** - The database you want to use. * - **USER** - - The username for authenticating to the database. + - The username for authenticating to the database, if your connection + requires authentication. * - **PASSWORD** - - The password for your database user. + - The password for your database user, if your connection requires authentication. * - **PORT** - - | The port number on which the database server is listening. + - | The port number on which the database server is listening. The default + port is ``27017``. | For MongoDB Atlas connections, this key is optional. * - **OPTIONS** - - A dictionary of additional connection options for the database. This key is optional. + - | A dictionary of additional connection options for the database. This key is optional. + | To see a full list of connection options that you can set in the ``OPTIONS`` key, + see the optional parameters for `MongoClient `__ + in the PyMongo API documentation. .. _django-manual-config-example: Example ``````` -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: -- 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``, which configures the driver to automatically retry certain write operations if they fail @@ -123,13 +138,6 @@ to a MongoDB deployment with the following configuration: }, } -.. tip:: - - To see a full list of connection options that you - can set in the ``OPTIONS`` key, see the optional - parameters for `MongoClient `__ - in the PyMongo API documentation. - .. _django-connection-configure-automatic: Automatically Configure Database Settings @@ -152,9 +160,8 @@ method accepts the following arguments: 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 ` +The following example uses the ``parse_uri()`` method to specify +the same connection configuration as the previous :ref:`manual configuration ` example: .. code-block:: python From f93519287f7f7bbb3337dc557d86b3f821b83463 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 13 Jan 2025 15:44:58 -0500 Subject: [PATCH 07/10] fixes --- source/configure-connection.txt | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/source/configure-connection.txt b/source/configure-connection.txt index f28b869e..597b2136 100644 --- a/source/configure-connection.txt +++ b/source/configure-connection.txt @@ -75,11 +75,8 @@ This nested dictionary has the following keys: | For SRV connections, you must include a scheme prefix (``mongodb+srv://``). | | To specify more than one host, include all hostnames in one string. Use - | a comma to separate each hostname, as shown in the following example: - - .. code-block:: python - - "HOST": "mongodb://mongos0.example.com:27017,mongos1.example.com:27017" + a comma to separate each hostname. + | **Example:** ``"HOST": "mongodb://mongos0.example.com:27017,mongos1.example.com:27017"`` * - **NAME** - The database you want to use. From 1049049a7c917429d03ab514c66ebac0fa955474 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 13 Jan 2025 16:28:09 -0500 Subject: [PATCH 08/10] MW feedback 2 --- source/configure-connection.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/configure-connection.txt b/source/configure-connection.txt index 597b2136..75efd28b 100644 --- a/source/configure-connection.txt +++ b/source/configure-connection.txt @@ -104,8 +104,8 @@ This nested dictionary has the following keys: Example ``````` -In this example, the ``DATABASES`` variable specifies the -following connection configuration: +In this example, the ``DATABASES`` variable performs the +following actions: - Sets the database to ``my_database`` - Provides authentication information for a database user From 11d4f2c4b995484ec0498700473e1016bc93df55 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 14 Jan 2025 10:50:31 -0500 Subject: [PATCH 09/10] AC feedback 2 --- snooty.toml | 2 +- source/configure-connection.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/snooty.toml b/snooty.toml index eead367f..1f5fb267 100644 --- a/snooty.toml +++ b/snooty.toml @@ -25,7 +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" +django-odm = "Django MongoDB Backend" language = "Python" mdb-server = "MongoDB Server" mongo-community = "MongoDB Community Edition" diff --git a/source/configure-connection.txt b/source/configure-connection.txt index 75efd28b..a55c2be8 100644 --- a/source/configure-connection.txt +++ b/source/configure-connection.txt @@ -20,8 +20,8 @@ Configure Your Database Connection Overview -------- -In this guide, you can learn how to connect your Django project to MongoDB -and configure the connection. +In this guide, you can learn how to configure your Django project's +connection to MongoDB. Connection Configuration ------------------------ @@ -36,7 +36,7 @@ your connection to MongoDB in the following ways: .. tip:: - To learn how to install the Django ODM and create a + To learn how to install {+django-odm+} and create a Django project, visit the :ref:`django-get-started` tutorial. .. _django-connection-configure-manual: From 90b7c5851863975d0810d19c25fc4f40cc9cf4be Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 14 Jan 2025 11:17:41 -0500 Subject: [PATCH 10/10] fix --- source/configure-connection.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/configure-connection.txt b/source/configure-connection.txt index a55c2be8..9d55dd93 100644 --- a/source/configure-connection.txt +++ b/source/configure-connection.txt @@ -32,7 +32,7 @@ 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. + the ``parse_uri()`` function. .. tip:: @@ -141,8 +141,8 @@ 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: +your MongoDB connection, you can use the ``parse_uri()`` function. This +function accepts the following arguments: - ``uri``: Your MongoDB connection URI. - ``conn_max_age``: Configures persistent database connections. @@ -157,8 +157,8 @@ method accepts the following arguments: Example ``````` -The following example uses the ``parse_uri()`` method to specify -the same connection configuration as the previous :ref:`manual configuration ` +The following example uses the ``parse_uri()`` function to specify +the same connection configuration as the previous :ref:`manual configuration ` example: .. code-block:: python