Integrating MongoDB Atlas with Django using Djongo

For the past month or so I’ve been on a journey to go learn full-stack development using various daunting tools and services ranging from AWS SAAS products to Django for web development and MongoDB (NoSQL) for the backend database. Having read the documentations and gone over the official learning guide for each of these tools and services it was time to bring them all together in one single project. While doing so, connecting the MongoDB with Django 3.0.7 was where things got complicated. This guide is to aid those who may be experiencing issues integrating the backend database with the Django framework.

Django currently does not support MongoDB as the backend database. In order for you to use MongoDB, you’ll need to install Djongo in your virtual environment.

pip install djongo

By installing Djongo your Django version may downgrade to 2.2.13, which you could check using the simple ‘pip freeze’ command. Now, you could choose to go ahead with this version of Django, however, for this guide, I’ll be updating it to the latest version.

pip install --upgrade django

We’ll now create a free-tier MongoDB cluster, if you don’t already have one.
Simply head to https://www.mongodb.com/try, sign-up for an account and create a free cluster (first option after signing up). For the cloud provider, I prefer to use AWS with a region closest to me, and you can choose whichever may better suit your needs.

Finally, create cluster and wait for it to deploy. This typically will take 3–4 minutes.
Once the cluster is up and running, you’ll need to create a database user. To do this, click “Database Access” on the left sidebar, and add a new database user with read and write privileges.

Next, you’ll need to whitelist your IP address through the “Network Access” tab on the left sidebar. For security reasons only add your IP address but for this guide, I’ll be allowing access from anywhere.

The last thing to do before connecting to your cluster is to create a database. Click on “Clusters” in the left sidebar and then click “collections”. On the collections page, click “Add My Own Data” and create the database.

Finally, time to connect the MongoDB database with your Django project. Before heading back to Django, copy the connection string of your database which can be found on the “Clusters” page. Click “connect” and “connect your application”. In my case, the connection string is: “mongodb+srv://sampleUser:<password>@cluster0-gbdot.mongodb.net/<dbname>?retryWrites=true&w=majority”

Before editing your Django project’s settings.py file, it is important that you install dnspython. DNSPython is used to connect to the Mongodb+srv:// URI.

pip install dnspython

Now, open your project’s settings.py file and scroll down until you see the database section. Change the code as follows, filling in the required information necessary:

DATABASE = {
    'default': {
        'ENGINE': 'djongo',
        "CLIENT": {
           "name": <your_database_name>,
           "host": <your_connection_string>,
           "username": <your_database_username>,
           "password": <your_database_password>,
           "authMechanism": "SCRAM-SHA-1",
        }, 
    }
}

Also, don’t forget to add your password and database name to the connection string. It should look something like this:

If we try migrating the project into the database it’ll cause pymongo connection error. This is because pymongo (installed with djongo) is trying to connect to the local mongoDB database instead of the host you’ve provided to the settings.py file. To resolve this issue, you’ll need to change the “HOST” variable in the mongo_client.py file to your connection string. This file is can be found in <virtualEnv>/lib/python<version>/site-packages/pymongo/mongo_client.py.

HOST = "mongodb+srv://sampleUser:samplePassword@cluster0-gbdot.mongodb.net/sampleDB?retryWrites=true&w=majority"

You should now be able to migrate to the MongoDB database.

python manage.py migrate

If for some reason you receive this error: “Djongo isn’t an available backend database”, downgrading pymongo to version 3.7.2 will do the trick.

Or, if you get an SQLDecodeError, downgrade sqlparse to a more stable version, i.e. 0.2.4.