Flask + MongoDB Tutorial

In this tutorial, I’ll demonstrate how can you use Flask together with MongoDB.


We’ll use the following structure for our project

__init__.py # Flask app
database.py # Main database class
job.py # Job DB model
routes.py # Main page routes
main.html # Main page HTML template
requirements.txt # Requirements for running the application

Flask Mongo Libraries

There are several libraries which provide you with simple integration and convenience helpers when it comes to using Flask together with MongoDB.

  • Flask-PyMongo
  • Flask-MongoEngine
  • Flask-MongoAlchemy 

For this tutorial purpose, we’ll use pymongo as it is, without any helper library.

Create the Flask application

Let’s start by adding the code for creating the application.

vi app/__init__.py

from flask import Flask

from app.database import DB

def create_app(config):
    app = Flask(__name__)
    return app

def register_blueprints(app):

    from app.main import bp as main_bp

A pretty standard function for creating a Flask application. First, we create an instance of Flask, then we initialize the database (we’ll write the code for it in the next section) and finally, we register the blueprints, which allows users to access our app routes.

If you are not familiar with blueprints, I recommend reading about them here. Personally, I find the concept of blueprints very useful, especially when you build large applications.

Add the database module

In order to connect to our database and run operations on it, we would want to have a generic module and class that we can use anywhere in our application code.

vi app/database.py

import pymongo
class DB(object):
    URI = "mongodb://"
    def init():
        client = pymongo.MongoClient(DB.URI)
        DB.DATABASE = client['sample_app']                                                                                                                                   
    def insert(collection, data):
    def find_one(collection, query):
        return DB.DATABASE[collection].find_one(query)

We have two basic functions the class adds – insert and find_one. We will use these functions in order to search for documents in our collections and insert new documents.

Note: if your database is using a different port, change the URI accordingly.

Add a Job Model

Now let’s create a model which represents our job. We will use his model for all the operations related to jobs collection in the database.

vi app/models/job.py

import datetime

from app.database import DB

class Job(object):

    def __init__(self, name):
        self.name = name
        self.created_at = datetime.datetime.utcnow()

    def insert(self):
        if not DB.find_one("jobs", {"name": self.name}):
            DB.insert(collection='jobs', data=self.json())

    def json(self):
        return {
            'name': self.name,
            'created_at': self.created_at

The first thing to note is that we import the DB class we created in the previous section. This is our connection to the database and we’ll use it for inserting and searching for jobs.

Next, our Jobs will have only two fields in the documents:

  • name – self-explanatory
  • created_at – datetime object which represents the date when the job was added to the database

The ‘insert’ method is the method responsible for inserting the job object into the database, using the ‘json’ method which returns a JSON representation of our object. Note it will only add the object if there is not already such job/document in the jobs collection.

Add Jobs

Now that we have the ability to add some jobs, let’s modify our app creation function to add them once the user started the application

vi app/__init__.py

from flask import Flask

from app.database import DB
from app.models.job import Job

def create_app(config):
    app = Flask(__name__)
    for job_name in ['job1', 'job2', 'job3']:
        new_job = Job(name=job_name)
    return app

def register_blueprints(app):

    from app.main import bp as main_bp

As you can see, we are adding three jobs to our database, using the names in the list. The ‘created_at’ attribute has a default value so we don’t need to pass it.

Main Route

Remember we registered a blueprint called ‘main’ in app/__init__.py? Well, then it’s time to define it. Let’s start by adding app/main/__init__.py

from flask import Blueprint
bp = Blueprint('main', __name__)
from app.main import routes  # noqa

As you can see we’ll define the routes in its own file in app/main/routes.py

from flask import render_template
from app.main import bp  # noqa
from app.models.job import Job 
def index():
    """Main page route."""
    button_text = "Add Job"
    return render_template('main.html', button_text=button_text)
def add_job():
    """Adds job4 to the database."""
    new_job = Job(name='job4')
    return ('', 204)

We defined two routes. First one (‘/’) is for users accessing our app. The only thing this route does is to render the main.html template which we will define in the next section. Every time a user will access our app this way http://x.x.x.x:5000/the main.html will be rendered and displayed to the user in its browser.

The second route (‘/add_job’) will be used to add a job named ‘job4’ when a user clicks on the button we’ll define in the ‘main.html’ template.

Main HTML template

Our main page will be very simple and will include only one simple button with the text “Add Job” on it.

<a id=link&gt;<button type="button" class="btn btn-info"&gt;{{ button_text }}</button&gt;</a&gt;                                                                                                   
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"&gt;</script&gt;
<script type=text/javascript&gt;
        $(function() {
          $('a#link').bind('click', function() {
                function(data) {
            return false;

This template will be rendered the moment the user access our app.

The jquery javascript code is used whenever the user clicks on the button to add a job. It will use the second route we defined for adding the job named ‘job4’.

A question for you to answer: will clicking multiple times on “Add Job” button will add multiple documents of “job4”?

Install requirements

Finally, don’t forget to set up the requirements for running the app successfully

vi requirements.txt


Run the application!

That’s it. Perhaps you have the simplest app ever created but it’s a start!

Now all you need to do is to install the requirements and run the app. From the app root directory run the following

virtualenv ~/app_venv && source ~/app_venv/bin/activate
pip install -r requirements.txt
flask run

That’s it. Your app is running! you should see in the terminal similar output to the following

 * Environment: production
   WARNING: Do not use the development server in a production environment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on (Press CTRL+C to quit)

Going to in the browser, you should see a button with “add job” string. Clicking on it, will add

You can verify it with mongo shell the following way

> use sample_app
switched to db sample_app
> db.jobs.find({})
{ "_id" : ObjectId("5c9218017c58a975d123ff8d"), "name" : "job1", "created_date" : ISODate("2019-03-20T10:37:53.353Z") }
{ "_id" : ObjectId("5c9218017c58a975d123ff8e"), "name" : "job2", "created_date" : ISODate("2019-03-20T10:37:53.382Z") }
{ "_id" : ObjectId("5c9218017c58a975d123ff8f"), "name" : "job3", "created_date" : ISODate("2019-03-20T10:37:53.383Z") }
{ "_id" : ObjectId("5c9218067c58a975d123ff90"), "name" : "job4", "created_date" : ISODate("2019-03-20T10:37:58.411Z") }

Few Notes

  • This is one of many possible structures. I usually prefer this one but it doesn’t mean you can’t use a different structure (e.g. skip using blueprints for no good reason :] )
  • A proper project would include several additional files for distributing the project, CLI support, static properties, etc. There are many great projects in GitHub demonstrating this.
  • You can find all the code snippets in this post in my flask-examples repository

3 thoughts on “Flask + MongoDB Tutorial

  1. I did exactly as you said . But when I executed the last command “flask run” I’m displayed with an error [ “Error: Could not locate a Flask application. You did not provide the “FLASK_APP” environment variable, and a “wsgi.py” or “app.py” module was not found in the current directory.” ] I also have the same doubt. You haven’t mentioned anything about “app.py” file itself


  2. You should do this in your terminal(command line): FLASK_APP=XXXX, where XXXX is the file you’re trying to run. So Flask know what’s going to look for.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s