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
