Configuration

This section provides guidance on how to configure your Django project to use django-documentdb.

Specifying the Default Primary Key Field

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

Change the following line in settings.py:

DEFAULT_AUTO_FIELD = "django_documentdb.fields.ObjectIdAutoField"

However, 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:

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_documentdb.fields.ObjectIdAutoField"


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


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

Each app reference in the INSTALLED_APPS setting must point to the corresponding AppConfig. For example, instead of 'django.contrib.admin', use '<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 DocumentDB/MongoDB. In the project template, settings.py specifies:

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

You can generate migrations if you’re setting things up manually or need to create migrations for third-party apps. For example:

python manage.py makemigrations admin auth contenttypes

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 ObjectIdAutoField:

default_auto_field = "django_documentdb.fields.ObjectIdAutoField"

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

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

(where “5.0” matches the version of Django that you’re using.)

Configuring the DATABASES Setting

After you’ve set up a project, configure Django’s DATABASES setting as follows:

DATABASES = {
    "default": {
        "ENGINE": "django_documentdb",
        "NAME": "my_database",
        "USER": "my_user",
        "PASSWORD": "my_password",
        "OPTIONS": {...},
    },
}

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

DocumentDB Connection Options

When connecting to DocumentDB, you can specify additional connection options in the OPTIONS dictionary. For example:

DATABASES = {
    "default": {
        # database settings
        "OPTIONS": {
            # Other options
            "authSource": "admin",
            "tls": True,
            "tlsCAFile": "/path/to/ca.pem",
            "retryWrites": False,
        },
    },
}

Connection Pooling Options

Connection pooling options can also be specified in the OPTIONS dictionary. For example:

DATABASES = {
    "default": {
        # database settings
        "OPTIONS": {
            # Other options
            "maxPoolSize": 30,
            "maxIdleTimeMS": 10 * 60 * 1000,
        }
    },
}

Congratulations, your project is ready to go!