Django Migrations Guide

How to use migrations

Django translates the models into respective database tables in the backend database with a
mechanism known as migration. It also propagates any changes in the model structure such as
adding, modifying or removing a field attribute of a model class to the mapped table.

Django’s migration system has the following commands:

makemigrations

migrate

sqlmigrate

showmigrations

Django’s migration is a version control system. Whenever you add a new model or effect changes in
an existing model, you need to run the makemigrations command. It creates a script for making
changes in the mapped table. Every time you run the makemigrations command and Django
detects the changes, a script with its name and version number is created. To implement the
changes according to the migration script, you need to run the migrate command.

Migrating Models of INSTALLED APPS

When you create a Django project with the startprojectcommand, certain apps are installed by
default. These apps are listed in the INSTALLED_APPS section in the project’s settings.py file.
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]
Data needs to be stored via these apps for their functionality to work. For example, the auth
package controls the users, groups, and permissions, so there must be corresponding tables
created in the database. Django uses the SQLite database by default. For that purpose, you run the
migrate command.
python manage.py migrate
Then, the tables required by the INSTALLED_APPS are created.
Let’s create an app inside our Django project.
(django) C:\django\myproject> python manage.py startapp myapp
1
(django) C:\django\myproject> python manage.py startapp myapp
This creates a myapp package folder inside the outer myproject folder. Inside myapp, a migrations

Printed using ChatGPT to PDF, powered by PDFCrowd HTML to PDF API. 1/8
 package is also created, which is empty to begin with.

Using the makemigrations command

Open the models.py file and add a person model to it.
from django.db import models
class Person(models.Model):
name = models.CharField(max_length=20)
email = models.EmailField()
phone = models.CharField(max_length=20)
The first step towards creating the Person table in the database is to run the makemigrations
command.
django) C:\django\myproject>python manage.py makemigrations
Migrations for 'myapp':
myapp\migrations\0001_initial.py
- Create model Person
Notice that in the migrations package, a migration script 0001_initial.py, is created. It indicates what
the script intends to do, which is: Create model Person.

If you open the migration file, you’ll find a migration class in it.
from django.db import migrations, models

class Migration(migrations.Migration):

initial = True

dependencies = [
]

operations = [
migrations.CreateModel(
name='Person',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False,
verbose_name='ID')),
('name', models.CharField(max_length=20)),
('email', models.EmailField(max_length=254)),
('phone', models.CharField(max_length=20)),
],
),
]
As mentioned above, you need to run the migrate command to apply the tasks in the migrations file
to be performed.
(django) C:\django\myproject>python manage.py migrate
Operations to perform:
Apply all migrations: admin, auth, contenttypes, myapp, sessions
Running migrations:
Applying myapp.0001_initial... OK
Have a look at the tables in your database db.sqlite3. The person table with three fields can be seen
in it.
Version control
Printed using ChatGPT to PDF, powered by PDFCrowd HTML to PDF API. 2/8
 Now, let's modify the person model class by changing the namefield to Person_name and running
makemigrations again.
(django) C:\django\myproject>python manage.py makemigrations
Was person.name renamed to person.person_name (a CharField)? [y/N] y
Migrations for 'myapp':
myapp\migrations\0002_rename_name_person_person_name.py
- Rename field name on person to person_name
A second migration script is created in the migrations folder. Before finalizing the change, add a
new field – age – in the person model and run makemigrations again.
(django) C:\django\myproject>python manage.py makemigrations
Migrations for 'myapp':
myapp\migrations\0003_person_age.py
- Add field age to person
Showmigrations command
Now there are two unmigrated changes in the model. Run the showmigrations command:
(django) C:\django\myproject>python manage.py showmigrations
...
...
myapp
[X] 0001_initial
[ ] 0002_rename_name_person_person_name
[ ] 0003_person_age
...
The initial migration (file numbered 0001) has already migrated. The X mark is indicative of this.
However, the next two migrations don’t show the X mark, which means they are pending. If we run
the migrate command, both modifications will be reflected in the table structure.
(django) C:\django\myproject>python manage.py migrate
Operations to perform:
Apply all migrations: admin, auth, contenttypes, myapp, sessions
Running migrations:
Applying myapp.0002_rename_name_person_person_name... OK
Applying myapp.0003_person_age... OK
As mentioned earlier, Django’s migration mechanism provides efficient version control. You may
want to fall back upon the table structure before adding the age field. Run the migrate command
and specify which migration file to be used so that the migrations after it will be undone or
unapplied.
(django) C:\django\myproject>python manage.py migrate myapp
0002_rename_name_person_person_name
Operations to perform:
Target specific migration: 0002_rename_name_person_person_name, from myapp
Running migrations:
Rendering model states... DONE
Unapplying myapp.0003_person_age... OK
sqlmigrate Command
Lastly, the sqlmigratecommand shows the SQL query or queries executed when a certain migration
script is run. For example, the first migration over the myapp’s person model is intended to create
the person table. The sqlmigratecommand for this script shows the CREATE TABLE statement for this
purpose.
(django) C:\django\myproject>python manage.py sqlmigrate myapp 0001_initial
BEGIN;
--
Printed using ChatGPT to PDF, powered by PDFCrowd HTML to PDF API. 3/8
 -- Create model Person
--
CREATE TABLE "myapp_person" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "name"
varchar(20) NOT NULL, "email" varchar(254) NOT NULL, "phone" varchar(20) NOT NULL);
COMMIT;
-> make it easy to understand

Understanding Django Migrations in Simple Terms

Django migrations help translate model changes into database tables and update them when needed.
This ensures that your database structure matches your models.

Main Commands in Django Migrations

1. `makemigrations` → Creates migration files (scripts) for changes in models.

2. `migrate` → Applies migration files to update the database.
3. `showmigrations` → Lists all migration files and their status.
4. `sqlmigrate` → Shows the SQL commands executed by a migration.

Step-by-Step Guide to Using Migrations

1. Default Migrations for Installed Apps

When you create a Django project, some apps like authentication and sessions are installed by default.
You need to apply their migrations so their database tables are created.
Run:

bash

python manage.py migrate

This will set up necessary tables like users, permissions, and sessions.

2. Creating a New App

To create a new app in your Django project, run:

bash

python manage.py startapp myapp

This creates a folder `myapp/` with a `migrations/` folder inside.

3. Creating a Model and Generating Migrations

Printed using ChatGPT to PDF, powered by PDFCrowd HTML to PDF API. 4/8
Define a model in `models.py`:

python

from django.db import models

class Person(models.Model):
name = models.CharField(max_length=20)
email = models.EmailField()
phone = models.CharField(max_length=20)

Generate migration files:

bash

python manage.py makemigrations

You'll see:

bash

Migrations for 'myapp':

myapp/migrations/0001_initial.py
- Create model Person

Now a migration file (`0001_initial.py`) is created in `migrations/`.

4. Applying Migrations

Run:

bash

python manage.py migrate

Output:

Applying myapp.0001_initial... OK

Now, the Person table is created in the database.

5. Modifying a Model and Version Control

Let’s rename `name` to `person_name` in `models.py`:

Printed using ChatGPT to PDF, powered by PDFCrowd HTML to PDF API. 5/8
 python

class Person(models.Model):
person_name = models.CharField(max_length=20)
email = models.EmailField()
phone = models.CharField(max_length=20)

Run `makemigrations` again:

bash

python manage.py makemigrations

Django will ask:

css

Was person.name renamed to person.person_name (a CharField)? [y/N]

Type `y`, and a new migration file is created.

If we also add a new field:

python

age = models.IntegerField()

Running `makemigrations` will generate:

bash

Migrations for 'myapp':

myapp/migrations/0003_person_age.py
- Add field age to person

6. Checking Pending Migrations

Run:

bash

python manage.py showmigrations

You'll see:

Printed using ChatGPT to PDF, powered by PDFCrowd HTML to PDF API. 6/8
 css

myapp
[X] 0001_initial
[ ] 0002_rename_name_person_person_name
[ ] 0003_person_age

Only 0001 is applied, the rest are pending.

Apply them:

bash

python manage.py migrate

7. Rolling Back to a Previous Migration

To undo the last migration:

bash

python manage.py migrate myapp 0002_rename_name_person_person_name

This removes 0003_person_age.

8. Viewing SQL Commands for Migrations

To see what SQL is executed:

bash

python manage.py sqlmigrate myapp 0001_initial

Example output:

sql

CREATE TABLE "myapp_person" (

"id" integer NOT NULL PRIMARY KEY AUTOINCREMENT,
"name" varchar(20) NOT NULL,
"email" varchar(254) NOT NULL,
"phone" varchar(20) NOT NULL
);

Summary

Printed using ChatGPT to PDF, powered by PDFCrowd HTML to PDF API. 7/8
 Command Purpose

`makemigrations` Creates migration files when models change

`migrate` Applies migration files to update the database

`showmigrations` Displays all migrations and their status

`sqlmigrate` Shows the SQL commands executed by a migration

`migrate myapp 0002` Rolls back migrations to a specific version

By using migrations, you ensure that changes in models are safely and systematically applied to your
database. 🚀

Printed using ChatGPT to PDF, powered by PDFCrowd HTML to PDF API. 8/8