Skip to content

Commit e35be75

Browse files
norareidynorareidy
committed
DOCSP-46328: Connection configuration
1 parent 5babfca commit e35be75

File tree

1 file changed

+163
-0
lines changed

1 file changed

+163
-0
lines changed

‎source/configure-connection.txt‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
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 connect your Django project to MongoDB
24+
and configure the connection.
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 updating the
33+
``DATABASES`` setting
34+
- :ref:`django-connection-configure-automatic` by using
35+
the ``parse_uri()`` method
36+
37+
.. tip::
38+
39+
To learn how to install the 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`` setting in your project's ``settings.py``
49+
file. The ``DATABASES`` setting has a ``default`` key,
50+
which you must specify to set MongoDB as the default database
51+
connection.
52+
53+
To specify the ``default`` key, include the following
54+
information:
55+
56+
- ``ENGINE``: The backend driver to use for the connection.
57+
Set this field to ``"django_mongodb_backend"``.
58+
59+
- ``HOST``: Your connection URI. For localhost connections,
60+
this field is optional. For SRV connections, you must include
61+
a scheme prefix (``mongodb+srv://``).
62+
63+
If connecting to a replica set or sharded cluster with multiple hosts, specify
64+
each host separated by a comma.
65+
66+
- ``NAME``: The database you want to use.
67+
68+
- ``USER``: The username for authenticating to the database.
69+
70+
- ``PASSWORD``: The password for your database user.
71+
72+
- ``PORT``: The port number on which the database server is listening.
73+
For MongoDB Atlas connections, this field is optional.
74+
75+
- ``OPTIONS``: A dictionary of additional connection options for the database.
76+
This field is optional.
77+
78+
.. _django-manual-config-example:
79+
80+
Example
81+
```````
82+
83+
This example specifies the ``DATABASES`` setting to connect
84+
to a MongoDB deployment with the following configuration:
85+
86+
- Connects to the ``sample_db`` database
87+
- Provides authentication information for a user
88+
whose username is ``my_user`` and password is ``my_password``
89+
- Uses the default MongoDB port (``27017``)
90+
- Sets the ``retryWrites`` connection option to ``true``,
91+
which configures the driver to automatically retry certain
92+
write operations if they fail
93+
- Sets the ``w`` connection option to ``majority``,
94+
which configures the driver to wait for acknowledgement from a majority
95+
of replica set members before performing write operations
96+
97+
.. code-block:: python
98+
99+
DATABASES = {
100+
"default": {
101+
"ENGINE": "django_mongodb_backend",
102+
"HOST": "mongodb+srv://cluster0.example.mongodb.net",
103+
"NAME": "my_database",
104+
"USER": "my_user",
105+
"PASSWORD": "my_password",
106+
"PORT": 27017,
107+
"OPTIONS": {
108+
"retryWrites": "true",
109+
"w": "majority",
110+
},
111+
},
112+
}
113+
114+
.. tip::
115+
116+
To see a full list of connection options that you
117+
can pass to the ``OPTIONS`` field, see the optional
118+
parameters for `MongoClient <https://pymongo.readthedocs.io/en/4.10.1/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
119+
in the PyMongo API documentation.
120+
121+
.. _django-connection-configure-automatic:
122+
123+
Automatically Configure Database Settings
124+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
125+
126+
To automatically construct the ``DATABASES`` setting that configures
127+
your MongoDB connection, you can use the ``parse_uri()`` method. This
128+
method accepts the following parameters:
129+
130+
- ``uri``: Your MongoDB connection URI.
131+
- ``conn_max_age``: Configures persistent database connections.
132+
This parameter is optional. To learn more, see
133+
`Persistent connections <https://docs.djangoproject.com/en/stable/ref/databases/#persistent-database-connections>`__
134+
in the Django documentation.
135+
- ``test``: Provides a dictionary of settings for test
136+
databases. This parameter is optional. To learn more, see
137+
`the TEST setting <https://docs.djangoproject.com/en/stable/ref/settings/#test>`__
138+
in the Django documentation.
139+
140+
Example
141+
```````
142+
143+
The following example uses the ``parse_uri()`` method to connect
144+
to a MongoDB deployment with the same configuration as
145+
the :ref:`manual configuration <django-manual-config-example>`
146+
example in this guide:
147+
148+
.. code-block:: python
149+
150+
import django_mongodb_backend
151+
152+
MONGODB_URI = "mongodb+srv://my_user:[email protected]/myDatabase?retryWrites=true&w=majority"
153+
DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI)
154+
155+
Additional Information
156+
----------------------
157+
158+
To view a sample project that configures a MongoDB database connection,
159+
see the :ref:`django-get-started-connect` step in the Getting Started
160+
tutorial.
161+
162+
To learn more about Django settings, see `Settings <https://docs.djangoproject.com/en/stable/ref/settings/>`__
163+
in the Django documentation.

0 commit comments

Comments
 (0)