Configuring a project to use Django MongoDB Backend

Aftering installing Django MongoDB Backend, you must take some additional steps to configure your project.

Specifying the default primary key field

In your Django settings, you must specify that all models should use ObjectIdAutoField.

You can create a new project that’s configured based on these steps using a project template:

$ django-admin startproject mysite --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.2.x.zip

(If you’re using a version of Django other than 5.2.x, replace the two numbers to match the first two numbers from your version.)

This template includes the following line in settings.py:

DEFAULT_AUTO_FIELD = "django_mongodb_backend.fields.ObjectIdAutoField"

But this setting won’t override any apps that have an AppConfig that specifies default_auto_field. For those apps, you’ll need to create a custom AppConfig.

For example, the project template includes <project_name>/apps.py:

from django.contrib.admin.apps import AdminConfig
from django.contrib.auth.apps import AuthConfig
from django.contrib.contenttypes.apps import ContentTypesConfig


class MongoAdminConfig(AdminConfig):
    default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField"


class MongoAuthConfig(AuthConfig):
    default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField"


class MongoContentTypesConfig(ContentTypesConfig):
    default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField"

Each app reference in the INSTALLED_APPS setting must point to the corresponding AppConfig. For example, instead of 'django.contrib.admin', the template uses '<project_name>.apps.MongoAdminConfig'.

Configuring migrations

Because all models must use ObjectIdAutoField, each third-party and contrib app you use needs to have its own migrations specific to MongoDB.

For example, settings.py in the project template specifies:

MIGRATION_MODULES = {
    "admin": "mongo_migrations.admin",
    "auth": "mongo_migrations.auth",
    "contenttypes": "mongo_migrations.contenttypes",
}

The project template includes these migrations, but you can generate them if you’re setting things up manually or if you need to create migrations for third-party apps. For example:

$ python manage.py makemigrations admin auth contenttypes
Migrations for 'admin':
  mongo_migrations/admin/0001_initial.py
    - Create model LogEntry
...

Creating Django applications

Whenever you run python manage.py startapp, you must remove the line:

default_auto_field = 'django.db.models.BigAutoField'

from the new application’s apps.py file (or change it to reference "django_mongodb_backend.fields.ObjectIdAutoField").

Alternatively, you can use the following startapp template which includes this change:

$ python manage.py startapp myapp --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.2.x.zip

(If you’re using a version of Django other than 5.2.x, replace the two numbers to match the first two numbers from your version.)

Configuring the DATABASES setting

After you’ve set up a project, configure Django’s DATABASES setting.

If you have a connection string, you can provide it like this:

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

Changed in version 5.2.1: Support for the connection string in "HOST" was added. Previous versions recommended using parse_uri().

Alternatively, you can separate the connection string so that your settings look more like what you usually see with Django. This constructs a DATABASES setting equivalent to the first 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",
            "tls": "false",
        },
    },
}

For a localhost configuration, you can omit HOST or specify "HOST": "localhost".

If you provide a connection string in HOST, any of the other values below will override the values in the connection string.

OPTIONS is an optional dictionary of parameters that will be passed to MongoClient.

Specify USER and PASSWORD if your database requires authentication.

PORT is optional if unchanged from MongoDB’s default of 27017.

For a replica set or sharded cluster where you have multiple hosts, include all of them in HOST, e.g. "mongodb://mongos0.example.com:27017,mongos1.example.com:27017".

Configuring the DATABASE_ROUTERS setting

If you intend to use embedded models, you must configure the DATABASE_ROUTERS setting so that a collection for these models isn’t created and so that embedded models won’t be treated as normal models by dumpdata:

DATABASE_ROUTERS = ["django_mongodb_backend.routers.MongoRouter"]

(If you’ve used the startproject template, this line is already present.)

Congratulations, your project is ready to go!

See also

Configuring Django’s contrib apps