Skip to content

Commit 519a551

Browse files
norareidynorareidy
committed
Merge remote-tracking branch 'upstream/master' into DOCSP-46327-create-index
2 parents abf9be5 + 5765e26 commit 519a551

36 files changed

+3079
-34
lines changed

‎snooty.toml

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,22 @@ name = "django"
22
title = "Django MongoDB Backend"
33

44
intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
5-
"https://www.mongodb.com/docs/atlas/objects.inv"
5+
"https://www.mongodb.com/docs/atlas/objects.inv",
6+
"http://docs.djangoproject.com/en/5.0/_objects/"
67
]
78

8-
# toc_landing_pages = ["/paths/to/pages/that/have/nested/content"]
9+
toc_landing_pages = [
10+
"/model-data",
11+
"/get-started",
12+
"/interact-data",
13+
]
914

1015
[constants]
1116
django-odm = "Django MongoDB Backend"
12-
api = "https://django-mongodb.readthedocs.io/en/latest/"
17+
api = "https://django-mongodb-backend.readthedocs.io/en/latest/"
1318
mdb-server = "MongoDB Server"
1419
django-version = "5.0"
1520
django-docs = "https://docs.djangoproject.com/en/{+django-version+}"
21+
framework = "Django"
22+
pymongo-version = "4.10"
23+
pymongo-docs = "https://www.mongodb.com/docs/languages/python/pymongo-driver/current"

‎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/get-started.txt

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
.. _django-get-started:
2+
3+
===============================
4+
Get Started with {+django-odm+}
5+
===============================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: tutorial
16+
17+
.. meta::
18+
:description: Learn how to create an app to connect to a MongoDB deployment by using Django MongoDB Backend.
19+
:keywords: quick start, tutorial, basics
20+
21+
.. toctree::
22+
23+
Download & Install </get-started/install/>
24+
Create a Deployment </get-started/create-deployment/>
25+
Create a Connection String </get-started/connection-string/>
26+
Configure a MongoDB Connection </get-started/connect-mongodb/>
27+
Create an Application </get-started/create-app/>
28+
Write Data to MongoDB </get-started/write-data/>
29+
Query MongoDB Data </get-started/query-data/>
30+
Create an Admin Site </get-started/create-admin/>
31+
Next Steps </get-started/next-steps/>
32+
33+
{+django-odm+} is a Django database backend that uses PyMongo to connect
34+
to MongoDB. This tutorial shows you how to create a Django app, connect to
35+
a MongoDB cluster hosted on MongoDB Atlas, and interact with data in your cluster.
36+
37+
.. tip::
38+
39+
MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB
40+
deployments. You can create your own free (no credit card required) MongoDB Atlas
41+
deployment by following the steps in this guide.
42+
43+
Follow this tutorial to connect a sample Django application to a MongoDB Atlas
44+
deployment.

‎source/get-started/connect-mongodb.txt

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
.. _django-get-started-connect:
2+
3+
=================================
4+
Configure your MongoDB Connection
5+
=================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: app, odm, code example
13+
14+
After installing {+django-odm+} and creating a MongoDB Atlas deployment,
15+
you can create a Django project that connects to MongoDB.
16+
17+
.. procedure::
18+
:style: connected
19+
20+
.. step:: Create a Django project
21+
22+
From your shell, run the following command to create a
23+
new Django project called ``quickstart`` based on a custom template:
24+
25+
.. code-block:: bash
26+
27+
django-admin startproject quickstart --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/{+django-version+}.x.zip
28+
29+
.. note:: Project Template
30+
31+
The ``django-mongodb-project`` template resembles the default Django project
32+
template but makes the following changes:
33+
34+
- Includes MongoDB-specific migrations
35+
- Modifies the ``settings.py`` file to instruct Django
36+
to use an ``ObjectId`` value as each model's primary key
37+
38+
After running this command, your ``quickstart`` project has
39+
the following file structure:
40+
41+
.. code-block:: bash
42+
:copyable: false
43+
44+
quickstart/
45+
manage.py
46+
mongo_migrations/
47+
__init__.py
48+
contenttypes/
49+
auth/
50+
admin/
51+
quickstart/
52+
__init__.py
53+
apps.py
54+
settings.py
55+
urls.py
56+
asgi.py
57+
wsgi.py
58+
59+
.. step:: Update your database settings
60+
61+
Open your ``settings.py`` file and navigate to the ``DATABASES`` setting.
62+
Replace this setting with the following code:
63+
64+
.. code-block:: python
65+
66+
DATABASES = {
67+
"default": django_mongodb_backend.parse_uri("<connection string URI>"),
68+
}
69+
70+
Replace the ``<connection string URI>`` placeholder with the connection string
71+
that you copied from the :ref:`django-get-started-connection-string`
72+
step of this guide. This configures your Django app to connect to
73+
your Atlas deployment and access the ``sample_mflix`` sample database.
74+
75+
.. step:: Start the server
76+
77+
To verify that you installed {+django-odm+} and correctly configured
78+
your project, run the following command from your project root:
79+
80+
.. code-block:: bash
81+
82+
python manage.py runserver
83+
84+
Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!"
85+
message and an image of a rocket.
86+
87+
After completing these steps, you have a Django project configured
88+
to use MongoDB.

0 commit comments

Comments
 (0)