Skip to content

Commit 6a1c617

Browse files
norareidynorareidy
authored
DOCSP-46328: Connection configuration (#6)
1 parent 8be45de commit 6a1c617

File tree

2 files changed

+186
-7
lines changed

2 files changed

+186
-7
lines changed

‎source/connect.txt

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
.. _django-connection-configuration:
2+
3+
==================================
4+
Configure Your Database Connection
5+
==================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, settings
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to configure your Django project's
24+
connection to MongoDB.
25+
26+
Connection Configuration
27+
------------------------
28+
29+
After installing {+django-odm+} and creating a project, you can configure
30+
your connection to MongoDB in the following ways:
31+
32+
- :ref:`django-connection-configure-manual` by specifying the
33+
``DATABASES`` variable in your project's settings.
34+
- :ref:`django-connection-configure-automatic` by using
35+
the ``parse_uri()`` function.
36+
37+
.. tip::
38+
39+
To learn how to install {+django-odm+} and create a
40+
Django project, visit the :ref:`django-get-started` tutorial.
41+
42+
.. _django-connection-configure-manual:
43+
44+
Manually Configure Database Settings
45+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46+
47+
To manually configure your connection to MongoDB, update
48+
the ``DATABASES`` variable in your project's ``settings.py``
49+
file. Set the ``DATABASES`` variable to a dictionary value containing
50+
the ``default`` key, as shown in the following example:
51+
52+
.. code-block:: python
53+
54+
DATABASES = {
55+
"default": {
56+
# Specify nested dictionary keys here
57+
},
58+
}
59+
60+
To configure the ``default`` key, assign a nested dictionary as its value.
61+
This nested dictionary has the following keys:
62+
63+
.. list-table::
64+
:header-rows: 1
65+
:widths: 20 80
66+
67+
* - Key
68+
- Description
69+
70+
* - **ENGINE**
71+
- The backend driver to use for the connection. Set this key to ``"django_mongodb_backend"``.
72+
73+
* - **HOST**
74+
- | Your connection URI. For localhost connections, this key is optional.
75+
| For SRV connections, you must include a scheme prefix (``mongodb+srv://``).
76+
|
77+
| To specify more than one host, include all hostnames in one string. Use
78+
a comma to separate each hostname.
79+
| **Example:** ``"HOST": "mongodb://mongos0.example.com:27017,mongos1.example.com:27017"``
80+
81+
* - **NAME**
82+
- The database you want to use.
83+
84+
* - **USER**
85+
- The username for authenticating to the database, if your connection
86+
requires authentication.
87+
88+
* - **PASSWORD**
89+
- The password for your database user, if your connection requires authentication.
90+
91+
* - **PORT**
92+
- | The port number on which the database server is listening. The default
93+
port is ``27017``.
94+
| For MongoDB Atlas connections, this key is optional.
95+
96+
* - **OPTIONS**
97+
- | A dictionary of additional connection options for the database. This key is optional.
98+
| To see a full list of connection options that you can set in the ``OPTIONS`` key,
99+
see the optional parameters for `MongoClient <https://pymongo.readthedocs.io/en/4.10.1/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
100+
in the PyMongo API documentation.
101+
102+
.. _django-manual-config-example:
103+
104+
Example
105+
```````
106+
107+
In this example, the ``DATABASES`` variable performs the
108+
following actions:
109+
110+
- Sets the database to ``my_database``
111+
- Provides authentication information for a database user
112+
whose username is ``my_user`` and password is ``my_password``
113+
- Specifies the default MongoDB port (``27017``)
114+
- Sets the ``retryWrites`` connection option to ``true``,
115+
which configures the driver to automatically retry certain
116+
write operations if they fail
117+
- Sets the ``w`` connection option to ``majority``,
118+
which configures the driver to wait for acknowledgement from a majority
119+
of replica set members before performing write operations
120+
121+
.. code-block:: python
122+
123+
DATABASES = {
124+
"default": {
125+
"ENGINE": "django_mongodb_backend",
126+
"HOST": "mongodb+srv://cluster0.example.mongodb.net",
127+
"NAME": "my_database",
128+
"USER": "my_user",
129+
"PASSWORD": "my_password",
130+
"PORT": 27017,
131+
"OPTIONS": {
132+
"retryWrites": "true",
133+
"w": "majority",
134+
},
135+
},
136+
}
137+
138+
.. _django-connection-configure-automatic:
139+
140+
Automatically Configure Database Settings
141+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142+
143+
To automatically construct the ``DATABASES`` setting that configures
144+
your MongoDB connection, you can use the ``parse_uri()`` function. This
145+
function accepts the following arguments:
146+
147+
- ``uri``: Your MongoDB connection URI.
148+
- ``conn_max_age``: Configures persistent database connections.
149+
This argument is optional. To learn more, see
150+
`Persistent connections <{+django-docs+}/ref/databases/#persistent-database-connections>`__
151+
in the Django documentation.
152+
- ``test``: Provides a dictionary of settings for test
153+
databases. This argument is optional. To learn more, see
154+
`the TEST setting <{+django-docs+}/ref/settings/#test>`__
155+
in the Django documentation.
156+
157+
Example
158+
```````
159+
160+
The following example uses the ``parse_uri()`` function to specify
161+
the same connection configuration as the previous :ref:`manual configuration <django-manual-config-example>`
162+
example:
163+
164+
.. code-block:: python
165+
166+
import django_mongodb_backend
167+
168+
MONGODB_URI = "mongodb+srv://my_user:[email protected]/my_database?retryWrites=true&w=majority"
169+
DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI)
170+
171+
Additional Information
172+
----------------------
173+
174+
To view a sample project that configures a MongoDB database connection,
175+
see the :ref:`django-get-started-connect` step in the Getting Started
176+
tutorial.
177+
178+
To learn more about Django settings, see `Settings <{+django-docs+}/ref/settings/>`__
179+
in the Django documentation.

‎source/index.txt

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,12 @@ Django MongoDB Backend
1212
.. toctree::
1313

1414
Get Started </get-started>
15+
Connection Configuration </connect>
1516
Interact with Data </interact-data>
1617
Issues & Help </issues-and-help>
1718
Compatibility </compatibility>
1819

1920
.. TODO:
20-
Connection Configuration </connect>
2121
Model Your Data </model-data>
2222
Django Feature Limitations </feature-limitations>
2323
API Documentation <{+api+}>
@@ -34,6 +34,12 @@ Get Started
3434
Learn how to install {+django-odm+}, establish a connection to MongoDB, and begin
3535
working with data in the :ref:`django-get-started` tutorial.
3636

37+
Connection Configuration
38+
------------------------
39+
40+
Learn how to configure a connection to a MongoDB deployment
41+
in the :ref:`django-connection-configuration` section.
42+
3743
Interact with Data
3844
------------------
3945

@@ -42,12 +48,6 @@ in the :ref:`django-interact-data` section.
4248

4349
.. TODO:
4450

45-
.. Connect to MongoDB
46-
.. ------------------
47-
48-
.. Learn how to configure a connection to a MongoDB deployment
49-
in the :ref:`django-connection-configuration` section.
50-
5151
.. Model Your Data
5252
.. ---------------
5353

0 commit comments

Comments
 (0)