Django MongoDB Backend Quickstart: Everything You Need to Know

Interested in diving into our Django MongoDB Backend integration? Follow along with this quickstart to create a Django application, connect that application to a MongoDB deployment, ensure your deployment is hosted on MongoDB Atlas, and interact with the data stored in your database using simple CRUD operations. Django MongoDB Backend integration Django application What is Django? Let’s first go over what Django is. Django is a high-speed model-view-controller framework for building web applications. There are a ton of key benefits of utilizing Django in projects, such as rapid development, a variety of services to choose from, great security, and impressive scalability. Django prides itself on being the best framework for producing flawless work efficiently. As we’ll see throughout this quickstart, it’s incredibly simple to get up and running with our Django MongoDB Backend integration. Django Pre-requisites To be successful with this quickstart, you’ll need a handful of resources: An IDE. This tutorial uses Visual Studio Code.Python 3.10 or later. We recommend using 3.12 in the environment.A MongoDB Atlas cluster. An IDE. This tutorial uses Visual Studio Code. Python 3.10 or later. We recommend using 3.12 in the environment. A MongoDB Atlas cluster. Create Your MongoDB Cluster Please follow the steps to create a MongoDB cluster on our free tier cluster, which is free forever. Please make sure that the “Network Settings” are correctly set up for easy connection to the cluster, and that a secure username and password have been chosen. Once the cluster is configured, please make sure the connection string is in a safe place for later use. create a MongoDB cluster Load the sample data into the cluster, and in the connection string, specify a connection to the sample database we are using, sample_mflix. Do this by adding the name of the database after the hostname, as shown in the code snippet below: sample_mflix mongodb+srv:// : @samplecluster.jkiff1s.mongodb.net/ ?retryWrites=true&w=majority&appName=SampleCluster mongodb+srv:// : @samplecluster.jkiff1s.mongodb.net/ ?retryWrites=true&w=majority&appName=SampleCluster Now that our cluster is ready, we can create our virtual environment! Create Your Virtual Environment Our first step is to create our Python virtual environment. Virtual environments allow us to keep the necessary packages and libraries for a specific project in the correct environment without having to make changes globally that could impact other projects. Python virtual environment To do this, run: python3.12 -m venv venv python3.12 -m venv venv Then, run: source venv/bin/activate source venv/bin/activate Once the (venv) is next to the directory name in the terminal, the virtual environment is correctly configured. Make sure that the Python version is correct (3.10 and above) by double-checking with: (venv) python —version python —version Once the virtual environment is set up, we can install our Django integration! Installing Django MongoDB Backend To install the Django integration, please run the following command from the terminal: pip install django-mongodb-backend pip install django-mongodb-backend If both PyMongo and Django are installed in the environment, please ensure that the PyMongo version is between 4.6 and 5.0, and that the Django version is between 5.0 and 5.1. When correctly run, this is what we’ll see in our terminal: Once this step is complete, our integration is correctly downloaded along with the dependencies that include Django and PyMongo required for success. Create Your Django Project! We’re all set up to create our Django project. This django-mongodb-project template is about the same as the default Django project template, with a couple of important changes. It includes MongoDB-specific migrations, and the settings.py file has been modified to make sure Django uses an ObjectId value for each model’s primary key. It also includes MongoDB-specific app configurations for Django apps that have default_auto_field set. This library allows us to create our own apps so we can set django_mongodb_backend.fields.ObjectIdAutoField. django-mongodb-project settings.py ObjectId default_auto_field django_mongodb_backend.fields.ObjectIdAutoField Run this command to create a new Django project called quickstart: quickstart django-admin startproject quickstart --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip django-admin startproject quickstart --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip Once this command is run, it will show up on the left-hand side of the project file: Once you can see the quickstart project, it’s time to update our database settings. To do this, go to the settings.py file under the quickstart folder and head over to the DATABASES setting. Replace the ” ” with the specific cluster URI, including the name of the sample database: quickstart settings.py quickstart DATABASES ” ” DATABASES = { "default": django_mongodb_backend.parse_uri(" "), } DATABASES = { "default": django_mongodb_backend.parse_uri(" "), } Now, we can make sure that we have correctly installed the Django MongoDB Backend and our project is properly set up. Make sure to be in the quickstart folder and run this command: quickstart python manage.py runserver python manage.py runserver Click on the link or visit http://127.0.0.1:8000/. On this page, there will be a “Congratulations!” and a picture of a rocket: http://127.0.0.1:8000/ Now that we know our setup has been successful, we can go ahead and create an actual application where we can interact with the sample data we previously downloaded! Let’s dive in. Creating an Application for Our “sample_mflix” Data We are first going to create our sample_mflix application. Head into the root directory of your project and run this command to create an application based on our custom template: sample_mflix python manage.py startapp sample_mflix --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip python manage.py startapp sample_mflix --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip The django-mongodb-app template makes sure that your apps.py file includes the line: “default_auto_field = ‘django_mongodb.fields.ObjectIdAutoField’”. This ensures that instead of using the original Django BigAutoField for IDs, we are using MongoDB’s specific ObjectId feature. django-mongodb-app apps.py BigAutoField Once you create your project, we are going to create models for our movie, viewer, and award data. Create Models for Our Movie, Viewer, and Award Data To create data models, all we have to do is open up our models.py file inside of our newly created sample_mflix directory and replace the entire file with the following code. models.py sample_mflix from django.db import models from django.conf import settings from django_mongodb_backend.fields import EmbeddedModelField, ArrayField from django_mongodb_backend.models import EmbeddedModel class Award(EmbeddedModel): wins = models.IntegerField(default=0) nominations = models.IntegerField(default=0) text = models.CharField(max_length=100) class Movie(models.Model): title = models.CharField(max_length=200) plot = models.TextField(blank=True) runtime = models.IntegerField(default=0) released = models.DateTimeField("release date", null=True, blank=True) awards = EmbeddedModelField(Award, null=True, blank=True) genres = ArrayField(models.CharField(max_length=100), null=True, blank=True) class Meta: db_table = "movies" managed = False def __str__(self): return self.title class Viewer(models.Model): name = models.CharField(max_length=100) email = models.CharField(max_length=200) class Meta: db_table = "users" managed = False def __str__(self): return self.name from django.db import models from django.conf import settings from django_mongodb_backend.fields import EmbeddedModelField, ArrayField from django_mongodb_backend.models import EmbeddedModel class Award(EmbeddedModel): wins = models.IntegerField(default=0) nominations = models.IntegerField(default=0) text = models.CharField(max_length=100) class Movie(models.Model): title = models.CharField(max_length=200) plot = models.TextField(blank=True) runtime = models.IntegerField(default=0) released = models.DateTimeField("release date", null=True, blank=True) awards = EmbeddedModelField(Award, null=True, blank=True) genres = ArrayField(models.CharField(max_length=100), null=True, blank=True) class Meta: db_table = "movies" managed = False def __str__(self): return self.title class Viewer(models.Model): name = models.CharField(max_length=100) email = models.CharField(max_length=200) class Meta: db_table = "users" managed = False def __str__(self): return self.name The Movie model here represents our sample_mflix.movies collection and stores information about various movies! The Viewer model, on the other hand, represents the sample_mflix.users collection and stores important user details for a movie streaming platform. The Award model represents the embedded document values that are stored in the Movie model. Movie sample_mflix.movies Viewer sample_mflix.users Award Movie Once this is done and the models.py file is saved, let’s create views to display our data. models.py Create Views to Display Our Data To display data from the sample_mflix database, we’ll add views to the views.pyfile. Open it up from your sample_mflix directory and replace the contents with the code below. sample_mflix views.py sample_mflix Here, we are displaying a landing page message and information about the Movieand Viewer models we configured above: Movie Viewer from django.http import HttpResponse from django.shortcuts import render from .models import Movie, Viewer def index(request): return HttpResponse("Hello, world. You're at the application index.") def recent_movies(request): movies = Movie.objects.order_by("-released")[:5] return render(request, "recent_movies.html", {"movies": movies}) def viewers_list(request): viewers = Viewer.objects.order_by("name")[:10] return render(request, "viewers_list.html", {"viewers": viewers}) from django.http import HttpResponse from django.shortcuts import render from .models import Movie, Viewer def index(request): return HttpResponse("Hello, world. You're at the application index.") def recent_movies(request): movies = Movie.objects.order_by("-released")[:5] return render(request, "recent_movies.html", {"movies": movies}) def viewers_list(request): viewers = Viewer.objects.order_by("name")[:10] return render(request, "viewers_list.html", {"viewers": viewers}) Once we have finished this section, we are ready to move on and configure URLs for our views. Configure URLs for Our Views To be successful in this section, we need to create a new file called urls.py inside of our sample_mflix directory. This file maps the views we defined in the previous step to dedicated URLs. urls.py sample_mflix Copy the code below into this new file: from django.urls import path from . import views urlpatterns = [ path("recent_movies/", views.recent_movies, name="recent_movies"), path("viewers_list/", views.viewers_list, name="viewers_list"), path("", views.index, name="index") ] from django.urls import path from . import views urlpatterns = [ path("recent_movies/", views.recent_movies, name="recent_movies"), path("viewers_list/", views.viewers_list, name="viewers_list"), path("", views.index, name="index") ] Once that has been copied in, we can go ahead to our quickstart/urls.py file and replace the file’s content with the code below: quickstart/urls.py from django.contrib import admin from django.urls import include, path urlpatterns = [ path("admin/", admin.site.urls), path("", include("sample_mflix.urls")), ] from django.contrib import admin from django.urls import include, path urlpatterns = [ path("admin/", admin.site.urls), path("", include("sample_mflix.urls")), ] Once we’ve finished replacing the file’s content, we can create templates to properly format our data. Create Templates to Format Your Data First, create a templates subdirectory inside of the sample_mflix directory. Once this subdirectory is created, create a recent_movies.html file inside it. We are going to copy the following code to format the movie data requested by the recent_movies view: templates sample_mflix recent_movies.html recent_movies Recent Movies Five Most Recent Movies {% for movie in movies %} {{ movie.title }} (Released: {{ movie.released }}) {% empty %} No movies found. {% endfor %} Recent Movies Five Most Recent Movies {% for movie in movies %} {{ movie.title }} (Released: {{ movie.released }}) {% empty %} No movies found. {% endfor %} Create another file in this same templates subdirectory and call it viewers_list.html. This template formats the user data that is requested by our viewers_list view. Copy the following code: templates viewers_list.html viewers_list Viewers List Alphabetical Viewers List Name Email {% for viewer in viewers %} {{ viewer.name }} {{ viewer.email }} {% empty %} No viewer found. {% endfor %} Viewers List Alphabetical Viewers List Name Email {% for viewer in viewers %} {{ viewer.name }} {{ viewer.email }} {% empty %} No viewer found. {% endfor %} Now that your templates are in place, we can include our application inside our project! Including Our Application Inside Our Project To do this, head over to the settings.py file nested in the quickstart directory and edit the INSTALLED_APPS section to look like this: settings.py quickstart INSTALLED_APPS INSTALLED_APPS = [ 'sample_mflix.apps.SampleMflixConfig', 'quickstart.apps.MongoAdminConfig', 'quickstart.apps.MongoAuthConfig', 'quickstart.apps.MongoContentTypesConfig', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', ] INSTALLED_APPS = [ 'sample_mflix.apps.SampleMflixConfig', 'quickstart.apps.MongoAdminConfig', 'quickstart.apps.MongoAuthConfig', 'quickstart.apps.MongoContentTypesConfig', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', ] Once that has been done, we can create migrations for our new models. Create Migrations for Your New Models We want to create migrations for our Movie, Award, and Viewer models and apply all these changes to the database. Head back to the root of your project and run the following commands: Movie Award Viewer python manage.py makemigrations sample_mflix python manage.py migrate python manage.py makemigrations sample_mflix python manage.py migrate Once the migrations are created, we have a basic Django MongoDB backend application! We can use this simple application to interact with our sample_mflixdatabase. This means running basic CRUD operations on the data. sample_mflix So, let’s go over how to do that. Write Data We are going to be working with a Python shell, so head back into the project’s root directory and bring up the shell with this command: python manage.py shell python manage.py shell Once you’re in your shell, we can import the necessary classes and modules for creating a datetime object. Do this by running the code below: datetime from sample_mflix.models import Movie, Award, Viewer from django.utils import timezone from datetime import datetime from sample_mflix.models import Movie, Award, Viewer from django.utils import timezone from datetime import datetime Now, we’re ready to insert a movie into our database! We can do this by running the code below to create a Movie object that stores data about a movie named “Minari”, including its awards: Movie “Minari” movie_awards = Award(wins=122, nominations=245, text="Won 1 Oscar") movie = Movie.objects.create( title="Minari", plot="A Korean-American family moves to an Arkansas farm in search of their own American Dream", runtime=217, released=timezone.make_aware(datetime(2020, 1, 26)), awards=movie_awards, genres=["Drama", "Comedy"] ) movie_awards = Award(wins=122, nominations=245, text="Won 1 Oscar") movie = Movie.objects.create( title="Minari", plot="A Korean-American family moves to an Arkansas farm in search of their own American Dream", runtime=217, released=timezone.make_aware(datetime(2020, 1, 26)), awards=movie_awards, genres=["Drama", "Comedy"] ) This Movie object actually stores incorrect data about the movie: the runtime value is listed as 217, but the correct value is 117. Movie runtime 217 117 Let’s fix this by running the code below: movie.runtime = 117 movie.save() movie.runtime = 117 movie.save() Now, let’s insert a viewer into our database as well. We can do this by creating a Viewer object that stores data about a viewer named “Abigail Carter”. Run the following code to do so: Viewer “Abigail Carter” viewer = Viewer.objects.create( name="Abigail Carter", email="abigail.carter@fakegmail.com" ) viewer = Viewer.objects.create( name="Abigail Carter", email="abigail.carter@fakegmail.com" ) Let’s delete a Viewer object. A movie viewer by the name of “Alliser Thorne” is no longer a member of the movie streaming service. To remove this viewer, run the code below: Viewer old_viewer = Viewer.objects.filter(name="Alliser Thorne").first() old_viewer.delete() old_viewer = Viewer.objects.filter(name="Alliser Thorne").first() old_viewer.delete() Once that’s done, exit your shell using this command: exit() exit() Ensure we are in the quickstart directory, and start the server using this command: quickstart python manage.py runserver python manage.py runserver Great! We can now go and make sure our Movies model was correctly inserted into the database. Do this by accessing the link: http://127.0.0.1:8000/recent_movies/ Movies http://127.0.0.1:8000/recent_movies/ This is what you’ll see, with our latest movie right on top: Let’s check our Viewer model, as well. Visit the link: http://127.0.0.1:8000/viewers_list/. Viewer http://127.0.0.1:8000/viewers_list/ There will be a list of 10 viewer names in our database. “Abigail Carter” will be at the top, and the viewer “Alliser Thorne” will have been deleted: Once these steps have been completed, documents in the sample_mflix sample database will have been inserted and edited. sample_mflix Now, we can query the data inside our database. Reading Back Our Data Open up your Python shell again, and please make sure that you have imported the necessary modules from when you first created the Python shell back under the step, “Write Data.” from sample_mflix.models import Movie, Award, Viewer from django.utils import timezone from datetime import datetime from sample_mflix.models import Movie, Award, Viewer from django.utils import timezone from datetime import datetime Once your shell is ready to go, we can query our users collection for a specific email. We want to query our sample_mflix.users collection for a user with the email ”jason_momoa@gameofthron.es”. Do this by running the following: sample_mflix.users ”jason_momoa@gameofthron.es” from sample_mflix.models import Movie, Viewer Viewer.objects.filter(email="jason_momoa@gameofthron.es").first() from sample_mflix.models import Movie, Viewer Viewer.objects.filter(email="jason_momoa@gameofthron.es").first() This will return the name of our user: Now, let’s query our movie collection for runtime values. In the same shell, run the following code to find movies that have a runtime value that is less than 10: runtime 10 Movie.objects.filter(runtime__lt=10) Movie.objects.filter(runtime__lt=10) This will return a list of matching movies, as seen in the screenshot below: Once this step is finished, feel free to run queries on any data stored inside the MongoDB cluster! Let’s Create an Admin Site It’s possible to create a Django admin site so that users can edit their data straight from a web interface. Let’s first create an admin user. From the root directory, run the following code: python manage.py createsuperuser python manage.py createsuperuser The terminal will ask for a username, email address, and password. Enter the following information below to create a user with specified credentials: Username: admin Email address: admin@example.com Password: Password (again): Username: admin Email address: admin@example.com Password: Password (again): To enter the admin site, run the following code: python manage.py runserver python manage.py runserver Access the site by visiting http://127.0.0.1:8000/admin/. A login screen will appear: http://127.0.0.1:8000/admin/ Enter the name and password that were created previously to log on. Here, the following information is presented, and users can edit their project authentication configuration through a selection of the Groups or Users rows in the Authentication and Authorization table. Groups Users Authentication and Authorization Let’s edit the data in our users sample collection. Remember that this is represented by the Viewer model, which is not associated with the Users row as shown in the admin panel. users Viewer Users Head to the sample_mflix/admin.py file and paste in the code below: sample_mflix/admin.py from django.contrib import admin from .models import Viewer admin.site.register(Viewer) from django.contrib import admin from .models import Viewer admin.site.register(Viewer) Refresh the Django administration site, and it will be updated: Now, we are able to select a viewer object. Do this by clicking on the Viewers row of the SAMPLE_MFLIX table to see the list of viewers, as seen below: Viewers SAMPLE_MFLIX At the top of the list, click on Abigail Carter. From here, we will be able to see the Name and Email. Abigail Carter Name Email Here, we are able to edit the information, if chosen. Users are able to edit any field and hit the SAVE button to save any changes. SAVE Great job, you have just completed the Django MongoDB Backend Quickstart! In this quickstart, you: Created a Django application. Connected your Django application to a MongoDB deployment. Ensured your deployment is hosted on MongoDB Atlas. Interacted with the data that is stored inside your cluster.Created a Django admin page. Created a Django application. Connected your Django application to a MongoDB deployment. Ensured your deployment is hosted on MongoDB Atlas. Interacted with the data that is stored inside your cluster. Created a Django admin page. To learn more about Django MongoDB Backend, please visit the docs and our repository on GitHub. docs repository This article is written by Anaiya Raisinghani (Developer Advocate @ MongoDB) and Nora Reidy (Technical Writer @ MongoDB). This article is written by Anaiya Raisinghani (Developer Advocate @ MongoDB) and Nora Reidy (Technical Writer @ MongoDB).