BlogAtlas Vector Search voted most loved vector database in 2024 Retool State of AI reportLearn more >>
MongoDB Developer
Sign in to follow topics
MongoDB Developer Centerchevron-right
Developer Topicschevron-right

How to Migrate Your Flask App From SQL To MongoDB

Muhammed Ali9 min read • Published Jun 28, 2024 • Updated Jun 28, 2024
Facebook Icontwitter iconlinkedin icon
Rate this tutorial
Migrating a Flask application from SQL to MongoDB involves several steps, as the two database systems have different paradigms. This article will guide you through converting an existing Flask blog application that uses SQLAlchemy to Flask-PyMongo to integrate MongoDB with the Flask application. We will explain the changes made to each file and the reasons behind them.
Understanding MongoDB
MongoDB is a NoSQL database known for its document-style kind of structure and ease of use.
Key concepts
  • Collections: Analogous to tables in SQL databases, collections in MongoDB store documents. However, unlike tables, collections do not enforce a schema, meaning each document can have different fields.
  • Documents: This is the primary data structure in MongoDB, similar to rows in SQL databases, but more complex. Documents are JSON-like objects that can contain arrays and nested subdocuments.
  • BSON: Binary representation of JSON is used internally by MongoDB. It extends JSON with additional data types, such as Date and Binary.

Differences between MongoDB and SQL databases

SchemaEnforces a fixed schema with predefined tables and columnsSchema-less, allowing for flexible and dynamic data models
Data StructureStores data in tables with rows and columnsStores data in collections of documents
RelationshipsUses foreign keys and joins to establish relationships between tablesEmbeds documents within other documents or references them, but lacks joins
Query LanguageUses Structured Query Language (SQL)Uses a rich, JSON-based query language
Planning the migration
Before migrating the Flask application from SQL to MongoDB, thorough planning is necessary to ensure a smooth transition and preserve data integrity.
Proper planning helps identify potential blockers and develop strategies to address them.

Steps required for migration

  • Set up MongoDB environment
  • Assess current SQL schema and relationships: Review the existing database schema, including tables, relationships, and data types. Identify complex queries and relationships that might require special handling in MongoDB.
  • Define the MongoDB schema: Design the MongoDB schema considering the document-oriented nature of the database. Map SQL tables and relationships to MongoDB collections and documents.
  • Backup existing data: Create a complete backup of the current SQL database to prevent data loss. Ensure backup processes are reliable and can be restored if needed.
  • Data transformation and migration strategy: Choose a migration tool or write custom scripts to handle data migration, as we will do in this article.
  • Update Flask application code: Modify Flask models to use MongoDB instead of SQLAlchemy. Update routes, forms, and templates to work with the new data structure. Test each module of the application to ensure compatibility with MongoDB.
  • Post-migration testing: Thoroughly test the application to ensure all functionalities are working as expected. Monitor performance and optimize queries and indexes in MongoDB.

Application features and structure

The application to be migrated is a Flask blog application with the following features:
  • Creating, editing, and viewing blog posts
  • Searching for blog posts
Setting up MongoDB for a Flask application
Before integrating MongoDB with a Flask application, the first step is to install MongoDB on your local machine. MongoDB provides detailed installation guides for various operating system versions.
Configuring MongoDB for Flask
After installing MongoDB, the next step is to configure it to work on your Flask application. This involves installing the Flask-PyMongo package and setting up the connection with your local mongo db server.
Flask-PyMongo is a Flask extension that makes it easy to use MongoDB instances in your Flask app.
Install it using pip:
You can also install Flask if you haven’t already.

Original SQL-based Flask application

Here’s a brief overview of the files in our original Flask application:
  • Defines the Post model using SQLAlchemy with attributes for id, title, content, and date_posted
  • Initializes the Flask application and SQLAlchemy
  • Contains form definitions using Flask-WTF
  • Manages database migrations using Flask-Script and Flask-Migrate
  • Contains the route definitions and logic for handling requests
What you will do is make a copy of the folder containing the old project. We will use the current file structure and just replace the current code with some new code.


Go to and paste in the following code:
This code defines a Post class that models a blog post for use with a MongoDB database, utilizing PyMongo's BSON types. The class includes an initializer (__init__ method) that sets the title, content, date posted, and a unique identifier for each post. If the date posted or identifier is not provided during instantiation, it defaults to the current UTC time and a new ObjectId, respectively. The class also provides a to_dict method to convert an instance into a dictionary format suitable for MongoDB storage, and a from_dict static method to create a Post instance from a dictionary. Additionally, the __repr__ method is defined to offer a clear string representation of the post, useful for debugging and logging.
The use of this is for the handling of blog post data within a Flask web application that uses MongoDB for its database. Converting the Post instances to and from dictionary format allows easy interaction with MongoDB's document-oriented storage.


Paste the following code into your file. The Flask application is initialized to use MongoDB through the Flask-PyMongo extension. The PyMongo instance (mongo) is set up with the Flask application which enables MongoDB support.  The application routes are imported to define the URL endpoints and their associated handlers.
Additionally, update the Config class in your to include MongoDB settings:

Update is used for database migrations in SQL, which isn't directly applicable to MongoDB so you can delete the file. If you need migrations, the Beanie ODM provides some support for migrations with MongoDB.


To make the Flask application compatible with MongoDB, several modifications were made to the routes to interact with MongoDB instead of SQLAlchemy. Firstly, the Post class instances are now converted to dictionaries using the to_dict method for storage in MongoDB. The home route retrieves all posts from the MongoDB collection using mongo.db.posts.find(), converts them to Post instances using the from_dict method, and then renders them.
For creating new posts in the new_post route, the post data is inserted into MongoDB with mongo.db.posts.insert_one(post.to_dict()). For retrieving, editing, and deleting posts, routes, post, edit_post, and delete_post use MongoDB's query methods (find_one_or_404, update_one, and delete_one) with ObjectId to handle the unique identifiers. The search route performs a text search on titles and content using MongoDB's regex capabilities, ensuring posts matching the query are fetched and rendered.
Migrating the data
The migration process involves exporting data from the existing SQL database and importing it into MongoDB. We will start by exporting the data from SQLite. On GitHub, you will find the db file we will use in this tutorial.
If you are using my db file, run the following code to query the database to list all tables and determine their names.
This Python code above connects to your existing SQLite database specified in the path db_path and retrieves the names of all tables within it, then closes the connection. The SQL query SELECT name FROM sqlite_master WHERE type='table'; is executed to fetch the names of all tables in the database. You should have post as your output.
After that, run the following code to export the data to a JSON file.
This Python code connects to your SQLite database, extracts all data from the post table, converts it to a JSON format, and saves it to a file.  A cursor object is created from this connection to execute SQL commands. The SQL query SELECT * FROM post is used to fetch all rows from the post table, and the results are stored in the rows variable. The variable column_names is used to extract the column names from the cursor's description attribute. Each row is then combined with the column names to create a list of dictionaries, where each dictionary represents a row of the table. And finally, the list is saved as a JSON file named post.json using the json.dump() function.
After running, you will then be provided with a JSON file (post.json) that looks like this:

Importing data into MongoDB

You can now import this JSON file into your MongoDB database. Here's a script to help you with that:
The connection string mongodb://localhost:27017/blogdb connects to your MongoDB instance running on localhost at port 27017 and uses the "blogdb" database. If the specified database does not exist, MongoDB will create it automatically when you first store data.

Update the templates

For the templates, you only need to change the variable for id. You will change all instances of to post_id=post._id.
You can now run the app with the following command:
Your application will be running on
the new app with MongoDB
You can find the complete application on GitHub.
Migrating a Flask application from SQL to MongoDB involves a deep understanding of the differences between both database systems and then planning to ensure a smooth transition. This article provided a step-by-step guide on how to convert an existing Flask blog application from using SQLAlchemy to using Flask-PyMongo to integrate MongoDB with the Flask application. We focused mainly on covering the necessary changes to each file. In a real-world scenario, there would be a need to construct a document schema from a tabular schema with joins and several queries. Even though this is a simple application, this tutorial covers the necessary steps to have a successful migration.
Want to continue the conversation? Head to the MongoDB Developer Community next.
Top Comments in Forums
There are no comments on this article yet.
Start the Conversation

Facebook Icontwitter iconlinkedin icon
Rate this tutorial

Getting Set Up to Run PHP with MongoDB

Jan 31, 2024 | 12 min read

Quick Start: BSON Data Types - Date

Sep 23, 2022 | 2 min read
Code Example


Feb 08, 2023 | 3 min read

Aggregation Pipeline: Applying Benford's Law to COVID-19 Data

Jan 26, 2023 | 16 min read
Table of Contents