From 44bf03e54dc043e8324af5de330b948377a663ee Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 16 Jan 2025 12:13:38 -0500 Subject: [PATCH] DOCSP-46328: Connection configuration --- source/connect.txt | 179 +++++++++++++++++++++++++++++++++++++++++++++ source/index.txt | 11 +-- 2 files changed, 185 insertions(+), 5 deletions(-) create mode 100644 source/connect.txt diff --git a/source/connect.txt b/source/connect.txt new file mode 100644 index 0000000..c37e27f --- /dev/null +++ b/source/connect.txt @@ -0,0 +1,179 @@ +.. _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 configure your Django project's +connection to MongoDB. + +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()`` function. + +.. tip:: + + To learn how to install {+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 ``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: + +.. 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://``). + | + | To specify more than one host, include all hostnames in one string. Use + a comma to separate each hostname. + | **Example:** ``"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, if your connection + requires authentication. + + * - **PASSWORD** + - The password for your database user, if your connection requires authentication. + + * - **PORT** + - | 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. + | 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 +``````` + +In this example, the ``DATABASES`` variable performs the +following actions: + +- Sets the database to ``my_database`` +- Provides authentication information for a database user + whose username is ``my_user`` and password is ``my_password`` +- 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 +- 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", + }, + }, + } + +.. _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()`` function. This +function 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 <{+django-docs+}/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 <{+django-docs+}/ref/settings/#test>`__ + in the Django documentation. + +Example +``````` + +The following example uses the ``parse_uri()`` function to specify +the same connection configuration as the previous :ref:`manual configuration ` +example: + +.. code-block:: python + + import django_mongodb_backend + + 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 +---------------------- + +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 <{+django-docs+}/ref/settings/>`__ +in the Django documentation. \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index ea41052..d309ee4 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,13 +11,14 @@ Django MongoDB Backend .. toctree:: + Connection Configuration Issues & Help Compatibility .. TODO: Get Started - Connection Configuration + Interact with Data Model Your Data Django Feature Limitations @@ -37,11 +38,11 @@ a Django database backend that uses PyMongo to connect to MongoDB. .. Learn how to install {+django-odm+}, establish a connection to MongoDB, and begin working with data in the :ref:`django-get-started` tutorial. -.. Connect to MongoDB -.. ------------------ +Connection Configuration +------------------------ -.. Learn how to configure a connection to a MongoDB deployment - in the :ref:`django-connection-configuration` section. +Learn how to configure a connection to a MongoDB deployment +in the :ref:`django-connection-configuration` section. .. Interact with Data .. ------------------