Configure Your Database Connection

Overview

In this guide, you can learn how to configure your Django project's connection to MongoDB.

Connection Configuration

After installing Django MongoDB Backend and creating a project, you can configure your connection to MongoDB by modifying the DATABASES setting in your project's settings.py file.

Tip

To learn how to install Django MongoDB Backend and create a Django project, visit the Get Started tutorial.

Set DATABASES to a dictionary containing the default key, as shown in the following code:

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:

Key	Description
ENGINE	The backend driver to use for the connection. Set this key to `"django_mongodb_backend"`.
HOST	The hostname. For localhost connections, this key is optional. For SRV connections, you must include a scheme prefix (`mongodb+srv://`). You can also specify a connection URI in this key. For more information, see Automatically Configure Database Settings. 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.

This section shows how to use the DATABASES setting to configure your connection in the following ways:

Automatically Configure Database Settings: Use the nested HOST key to specify your connection URI and configure connection settings automatically.
Manually Configure Database Settings: Specify connection settings across multiple dictionary keys.

Automatically Configure Database Settings

Important

Added in v5.2.1

Django MongoDB Backend v5.2.1 adds support for specifying a connection URI in the nested HOST key. If you use a previous version, you can still manually configure your connection or use the parse_uri() function.

To specify connection settings in your connection URI, set the following nested default keys:

ENGINE: Set to "django_mongodb_backend".
HOST: Set to your connection URI.
NAME: Set to the name of the database you want to use.

All other keys described in the previous section are optional.

Example

This example uses only the ENGINE, HOST, and NAME keys to configure a connection to MongoDB. The DATABASES setting performs the following actions:

Provides authentication information for a database user whose username is my_user and password is my_password
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
Sets the database to my_database

DATABASES = {
    "default": {
        "ENGINE": "django_mongodb_backend",
        "HOST": "mongodb+srv://my_user:my_password@cluster0.example.mongodb.net/?retryWrites=true&w=majority",
        "NAME": "my_database",
}

Note

If you specify additional keys in the DATABASES setting, the values in those keys override any conflicting values parsed from the connection URI.

Manually Configure Database Settings

You can manually configure your connection settings by specifying connection information across the default keys.

Example

This example uses dictionary keys to configure the same database connection as the previous example:

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",
        },
    },
}

Additional Information

To view a sample project that configures a MongoDB database connection, see the Configure your MongoDB Connection step in the Getting Started tutorial.

To learn more about Django settings, see Settings in the Django documentation.

Back

Next Steps

Model Your Data