Django Database Migrations: A Comprehensive Overview

Table of Contents

• Introduction to Django databases
• Django’s database migration solution
  • Change the contract: Django’s ORM
  • Plan for change: generate migrations
  • Execute: apply migrations
  • Tracking changes with Django
  • Rolling back with Django
• A simple Django database migrations example
  • The initial Django application
  • Changing the Django data model
  • Generate the Django database migration
  • Applying the Django database migration
  • Bonus: data migrations
  • Rolling back the Django database example
• What next?
• Addendum: Life without a migration tool
  • Change the contract: database schema and application code changes
  • Plan for change: write a migration script in SQL
  • Execute: deploy code and run migration in unison
  • Tracking changes without Django
  • Rolling back without Django

Introduction to Django databases

The Django web framework is designed to work with an SQL-based relational database backend, most commonly  PostgreSQL or MySQL. If you’ve never worked directly with a relational database before, managing how your data is stored/accessed and keeping it consistent with your application code is an important skill to master. 

You’ll need a contract between your database schema (how your data is laid out in your database) and your application code, so that when your application tries to access data, the data is where your application expects it to be. Django provides an abstraction for managing this contract in its ORM (Object-Relational Mapping). 

Over your application’s lifetime, it’s very likely that your data needs will change. When this happens, your database schema will probably need to change as well. Effectively, your contract (in Django’s case, your Models) will need to change to reflect the new agreement, and before you can run the application, the database will need to be migrated to the new schema. 

Django’s ORM comes with a system for managing these migrations to simplify the process of keeping your application code and your database schema in sync.

Django’s database migration solution

Django’s migration tool simplifies the manual nature of the migration process described above while taking care of tracking your migrations and the state of your database. Let’s take a look at the three-step migration process with Django’s migration tool.

1. Change the contract: Django’s ORM

In Django, the contract between your database schema and your application code is defined using the Django ORM. You define a data model using Django ORM’s models and your application code interfaces with that data model. 

When you need to add data to the database or change the way the data is structured, you simply create a new model or modify an existing model in some way. Then you can make the required changes to your application code and update your unit tests, which should verify your new contract (if given enough testing coverage).

2. Plan for change: generate migrations

Django maintains the contract largely through its migration tool. Once you make changes to your models, Django has a simple command that will detect those changes and generate migration files for you.

3. Execute: apply migrations

Back to Top