Set up PostgreSQL and MongoDB in Django using Docker

Set up PostgreSQL and MongoDB in Django using Docker
Add MongoDB and PostgreSQL in Django using Docker

In this post, you'll learn how to integrate multiple databases with the Django framework and navigate incoming data using a DB router that automatically writes them to the required database.

Real-world example scenario

Usually, the majority of projects are using relational databases such as Postgres or MySQL but sometimes we also need NoSQL databases to hold extra heavy data which decrease the overload of relational databases.

Assume that your project generates tons of logs while processing some heavy tasks in a queue. These log objects must be stored in non-relational databases instead of hitting relational databases each time and extremely overloading them with huge messy log objects. I guess you spot the problem here, so let's take a look at what can we do about it...

Setting up environment

Create an empty directory named app then let's start by creating a Dockerfile that will copy our working directory and also install required dependencies for Python and Postgres.


FROM python:3.8-slim

RUN apt-get update \
    && apt-get upgrade -y \
    && apt-get install -y \
    build-essential \
    libssl-dev \
    libffi-dev \
    python3-dev \
    build-essential \
    libjpeg-dev \
    zlib1g-dev \
    gcc \
    libc-dev \
    bash \
    git \
    && pip3 install --upgrade pip

ENV LIBRARY_PATH=/lib:/usr/lib



COPY . /app

RUN pip3 --no-cache-dir install -r requirements.txt

These wheel packages will be used while installing and setting up Postgres and other services in the system. Now, we need to add requirements.txt to install the required packages for our project.



We are going to use djongo which will help to convert SQL to MongoDB query. By using djongo we can use MongoDB as a backend database for our Django project. At the time of writing this post, djongo has issues supporting Django versions above v.3+, but it can be resolved easily by just by changing the version from the package itself by forking it to your repository. There is a file named that holds configuration settings and you'll see the block named install_requires where the supported version is mentioned (Don't forget to fork it first).

install_requires = [

We just need to refactor it to fit with our current version of Django. I am using 3.1.3 so I will replace the 3.0.5 to 3.1.3 and it will look like below:

install_requires = [

Once you finished, search for requirements.txt and change the Django version there as well:

requirements.txt (in djongo)


That's it! Commit your changes to the forked repository and then you need to include it to your requirements.txt file but this time it will get from your forked repository like below:


You don't have to go through all these processes because I already included it as you can see from above (requirements.txt) so feel free to use mine if your Django version is 3.1.3 as well.

There are some other dependencies like celery where we'll use it as the queue to pass time-consuming tasks to run in the background and redis is just a message broker for celery. This topic is out of scope for this post but you can visit Dockerizing Django with Postgres, Redis and Celery to understand it more.

Now it's time to set up our services by configuring compose file. Create this file in a root level of your current directory which means it will be outside of app directory There are going to be 5 services in total:

  1. mongodb - for setting up MongoDB
  2. postgres - for setting up PostgreSQL
  3. app - Django project
  4. celery - Queue for tasks
  5. redis - Message broker that required for celery


version: '3'


    image: mongo
    container_name: mongo
    restart: always
    env_file: .env
      - ${PWD}/_data/mongo:/data/db
      - ${PWD}/docker/_mongo/fixtures:/import
      - ${PWD}/docker/_mongo/scripts/
      - 27017:27017

    container_name: postgres
    image: postgres:12
    restart: always
    env_file: .env
      - POSTGRES_DB=app_db
      - POSTGRES_USER=app_db_user
      - POSTGRES_PASSWORD=supersecretpassword
      - POSTGRES_PORT=5432
      - 5432:5432
      - ${PWD}/_data/postgres:/var/lib/postgresql/data
      - ${PWD}/docker/_postgres/scripts/create_test_db.sql:/docker-entrypoint-initdb.d/docker_postgres_init.sql

    image: redis:6
    container_name: redis
    restart: always
    env_file: .env
    command: redis-server --requirepass $REDIS_PASSWORD
      - 6379:6379
      - ${PWD}/_data/redis:/var/lib/redis

    build: ./app
    image: app:latest
    container_name: app
    restart: always
    command: "python runserver"
    env_file: .env
      - ${PWD}/app:/app
      - 8000:8000
      - postgres
      - redis

    build: ./app
    image: app:latest
    container_name: celery
    restart: always
    command: [
    env_file: .env
      - DJANGO_SETTINGS_MODULE=app.settings
      - DJANGO_WSGI=app.wsgi
      - DEBUG=False
      - ${PWD}/app:/app
      - postgres
      - redis


I will not go through this configuration in detail by assuming you already have knowledge about docker and compose files. Simply, we are pulling required images for the services and setting up main environment variables and ports to complete the configuration.

Now we also need to add .env file to fetch values of environment variables while building services:


# Mongo DB

# PostgreSQL

# Redis

Next, we'll create a new Django project inside our app folder:

docker-compose run app sh -c "django-admin startproject app ."

The project structure should be like below:

├── app
│   ├── app
│   │   ├──
│   │   ├──
│   │   ├──
│   │   ├──
│   │   └──
│   ├── Dockerfile
│   ├──
│   └── requirements.txt
├── docker-compose.yml
└── .env

If you see dbsqlite in project files then you should delete it since we'll use postgres it as a relational database. You also will notice _data directory which represents the volume of MongoDB and Postgres.

Integration with PostgreSQL

We are ready to add our primary relational database which is going to be postgres. Navigate to and update DATABASES configuration like below:

    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': os.environ.get('POSTGRES_HOST'),
        'NAME': os.environ.get('POSTGRES_NAME'),
        'USER': os.environ.get('POSTGRES_USER'),
        'PASSWORD': os.environ.get('POSTGRES_PASSWORD'),
        'PORT': os.environ.get('POSTGRES_PORT', 5432),


The default database set to postgres and environment variables will be fetched from .env file. Sometimes, postgres is having connection issues caused by racing issues between Django and postgres. To prevent such situations we'll implement a custom command and add it to commands block in compose file. In this way, Django will wait  postgres before launch.

The recommended path of holding commands is /core/management/commands/ from the official documentation of Django. So let's create an app named core then create a management/commands directory inside it.

docker-compose run app sh -c "django-admin startapp core"

Then add following command to hold Django until postgres is available:


import time
from django.db import connections
from django.db.utils import OperationalError
from import BaseCommand

class Command(BaseCommand):
    """Django command to pause execution until db is available"""

    def handle(self, *args, **options):
        self.stdout.write('Waiting for database...')
        db_conn = None
        while not db_conn:
                db_conn = connections['default']
            except OperationalError:
                self.stdout.write('Database unavailable, waititng 1 second...')

        self.stdout.write('Database available!'))

Make sure you included into sub-directories you created. Now update app service in compose file by adding this command:


    build: ./app
    image: app:latest
    container_name: app
    restart: always
    command: >
        sh -c "python wait_for_db &&
               python migrate &&
               python runserver"
    env_file: .env
      - ${PWD}/app:/app
      - 8000:8000
      - postgres
      - redis

Consider the command block only and you'll see we now have two commands there.

Integration with MongoDB

Actually, the integration of MongoDB is so simple thanks to djongo which handles everything behind the scenes. Switch to again and we'll add our second database as nonrel which stands for the non-relational database.

    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': os.environ.get('POSTGRES_HOST'),
        'NAME': os.environ.get('POSTGRES_NAME'),
        'USER': os.environ.get('POSTGRES_USER'),
        'PASSWORD': os.environ.get('POSTGRES_PASSWORD'),
        'PORT': os.environ.get('POSTGRES_PORT'),

    "nonrel": {
        "ENGINE": "djongo",
        "NAME": os.environ.get('MONGO_DB_NAME'),
        "CLIENT": {
            "host": os.environ.get('MONGO_DB_HOST'),
            "port": int(os.environ.get('MONGO_DB_PORT')),
            "username": os.environ.get('MONGO_DB_USERNAME'),
            "password": os.environ.get('MONGO_DB_PASSWORD'),
        'TEST': {
            'MIRROR': 'default',

The same logic applies here as we did for default database which is postgres.

Setting up DB router

DB router which will automatically write objects to a proper database such as whenever the log object created it should navigate to mongodb instead of postgres. Setting up a DB router is simple, we just need to use router methods that Django provides and define our non-rel models to return the proper database.

Create a new directory named utils inside the core app and also add to mark it as a python package. Then add the new file which is DB router below:


class NonRelRouter:
    A router to control if database should use
    primary database or non-relational one.

    nonrel_models = {'log'}

    def db_for_read(self, model, **_hints):
        if model._meta.model_name in self.nonrel_models:
            return 'nonrel'
        return 'default'

    def db_for_write(self, model, **_hints):
        if model._meta.model_name in self.nonrel_models:
            return 'nonrel'
        return 'default'

    def allow_migrate(self, _db, _app_label, model_name=None, **_hints):
        if _db == 'nonrel' or model_name in self.nonrel_models:
            return False
        return True

nonrel_models - We are defining the name of our models in lowercase which belongs to a non-rel database or mongodb.

db_for_read - the function name is self-explanatory so basically, it is used for reading operations which means each time we try to get records from the database it will check where it belongs and return the proper database.

db_for_write - the same logic applies here. It's used to pick a proper database for writing objects.

allow_migrate - Decided if the model needs migration. In mongodb there is no need to run migrations since it's a non-rel database.

Next, we should add extra configuration in to activate our custom router:


DATABASE_ROUTERS = ['core.utils.db_routers.NonRelRouter', ]


Great! Our database configurations are finished and now it's time to make a few changes in Django as well before launching everything.

Setting up Celery and Redis

This part is a bit out of scope but since I want to illustrate some real-world app then those tools are always present in projects to handle heavy and time-consuming tasks. Let's add celery to our project, but it should place in our project folder alongside with settings file:

import os
from celery import Celery

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'app.settings')

app = Celery('app')
app.config_from_object('django.conf:settings', namespace='CELERY')

Basically, it will discover all tasks alongside the project and will pass them to the queue. Next, we also need to update file inside the current directory, which is our Django project:

from .celery import app as celery_app

__all__ = ['celery_app']

Celery requires a broker URL for tasks so in this case, we will use Redis as a message broker. Open your settings file and add the following configurations:


CELERY_BROKER_URL = os.environ.get('CELERY_URL')


Now try to run docker-compose up -d and all services should start successfully.

Adding models and celery tasks

In this section, we'll pass a new task to the celery queue and test if our DB router works properly and writes objects to the required database. Create a new directory inside the core app named models and add the following file inside it to hold MongoDB models :


from djongo import models as mongo_models

class Log(mongo_models.Model):
    _id = mongo_models.ObjectIdField()
    message = mongo_models.TextField(max_length=1000)

    created_at = mongo_models.DateTimeField(auto_now_add=True)
    updated_at = mongo_models.DateTimeField(auto_now=True)

    class Meta:
        _use_db = 'nonrel'
        ordering = ("-created_at", )

    def __str__(self):
        return self.message

As you see it's a very simple Log model where it will let us know what's going on behind the scenes of internal operations of our application. Then add a model for Postgres as well:


from django.db import models

class Post(models.Model):
    title = models.CharField(max_length=255)
    description = models.TextField()

    def __str__(self):
        return self.title

We are going to generate random posts and make some of them fail in order to write error logs for failed data.

Lastly, don't forget to include inside models directory:


from .postgres_models import *
from .mongo_models import *

Now we need to create a celery task that will generate tons of posts with random values by using Faker generators:


import logging
import random
from faker import Faker
from .models import Post
from celery import shared_task

from core.utils.log_handlers import LoggingHandler

logger = logging.getLogger(__name__)

def create_random_posts():
    fake = Faker()
    number_of_posts = random.randint(5, 100)
    for i in range(number_of_posts):
            if i % 5 == 0:
                title = None
                title = fake.sentence()
            description = fake.text()
                title = title,
                description = description,
        except Exception as exc:
            logger.error("The post number %s failed due to the %s", i, exc)

By adding if statement there we are forcing some of the posts to fail in order to catch exceptions and write them to mongodb. As you noticed, we are using a custom log handler that will write the log data right away after its produced. So, create a new file named inside utils folder:


import logging

from core.models import Log

class LoggingHandler(logging.Handler):
    """Save log messages to MongoDB

    def emit(self, record):

Great! We are almost ready to launch.

Lastly, let's finish creating a very simple view and URL path to trigger the task from the browser and return JSON a response if the operation succeeded.


from django.http.response import JsonResponse
from .tasks import create_random_posts

def post_generator(request):
    return JsonResponse({"success": True})

from django.contrib import admin
from django.urls import path

from core.views import post_generator

urlpatterns = [
    path('', post_generator)

Include the core app inside INSTALLED_APPS configuration in then run the migrations and we're done!

docker-compose run app sh -c "python makemigrations core"

Now, if you navigate to the task will be passed to the queue and post objects will start to generate. Try to visit admin and you'll see log objects created successfully and by this way we're avoiding overload postgres while it handles only relational data.

Source Code

GitHub - thepylot/django-mongodb-postgres: Integration of multiple databases with Django framework and navigate incoming data using DB router which automatically writes them to required database.
Integration of multiple databases with Django framework and navigate incoming data using DB router which automatically writes them to required database. - GitHub - thepylot/django-mongodb-postgres:...

Support 🌏

If you feel like you unlocked new skills, please share them with your friends and subscribe to the youtube channel to not miss any valuable information.