Using migrations

In Agile software development, requirements for the project evolve and get updated from time to time in the process of development. As development happens iteratively, you will have to perform database schema changes along the way. With Django migrations, you don't have to change the database tables and fields manually, as most of it is done automatically, using the command-line interface.

Getting ready

Activate your virtual environment in the command-line tool, and change the active directory to your project's directory.

How to do it...

To create the database migrations, take a look at the following steps:

1. When you create models in your new categories or ideas app, you have to create an initial migration that will create the database tables for your app. This can be done by using the following command:

(env)$ python manage.py makemigrations ideas

2. The first time that you want to create all of the tables for your project, run the following command:

(env)$ python manage.py migrate

Run this command when you want to execute the new migrations for all of your apps.

3. If you want to execute the migrations for a specific app, run the following command:

(env)$ python manage.py migrate ideas

4. If you make some changes in the database schema, you will have to create a migration for that schema. For example, if we add a new subtitle field to the idea model, we can create the migration by using the following command:

(env)$ python manage.py makemigrations --name=subtitle_added ideas

However, the --name=subtitle_added field can be skipped because in most cases Django generates fairly self-explanatory default names.

5. Sometimes, you may have to add to or change data in the existing schema in bulk, which can be done with a data migration, instead of a schema migration. To create a data migration that modifies the data in the database table, we can use the following command:

(env)$ python manage.py makemigrations --name=populate_subtitle \
> --empty ideas

The --empty parameter tells Django to create a skeleton data migration, which you have to modify to perform the necessary data manipulation before applying it. For data migrations, setting the name is recommended.

6. To list all of the available applied and unapplied migrations, run the following command:

(env)$ python manage.py showmigrations

The applied migrations will be listed with an [X] prefix. The unapplied ones will be listed with a [ ] prefix.

7. To list all of the available migrations for a specific app, run the same command, but pass the app name, as follows:

(env)$ python manage.py showmigrations ideas

How it works...

Django migrations are instruction files for the database migration mechanism. The instruction files inform us about which database tables to create or remove, which fields to add or remove, and which data to insert, update, or delete. Also they define which migrations are dependent on which other migrations.

There are two types of migrations in Django. One is schema migration, and the other is data migration. Schema migration should be created when you add new models, or add or remove fields. Data migration should be used when you want to fill the database with some values or massively delete values from the database. Data migrations should be created by using a command in the command-line tool, and then coded in the migration file.

The migrations for each app are saved in their migrations directories. The first migration will usually be called 0001_initial.py, and the other migrations in our example app will be called 0002_subtitle_added.py and 0003_populate_subtitle.py. Each migration gets a number prefix that is automatically incremented. For each migration that is executed, there is an entry that is saved in the django_migrations database table.

It is possible to migrate back and forth by specifying the number of the migration to which we want to migrate, as shown in the following command:

(env)$ python manage.py migrate ideas 0002

To unmigrate all migrations of the app including the initial migration, run the following:

(env)$ python manage.py migrate ideas zero

Unmigrating requires each migration to have both a forward and a backward action. Ideally, the backward action would undo exactly the changes made by the forward action. However, in some cases such a change would be unrecoverable, such as when the forward action has removed a column from the schema, because it will have destroyed data. In such a case, the backward action might restore the schema, but the data would remain lost forever, or else there might not be a backward action at all.

Do not commit your migrations to version control until you have tested the forward and backward migration process and you are sure that they will work well in other developments and public website environments.

There's more...

Learn more about writing database migrations in the official How To guide, found at https://docs.djangoproject.com/en/2.2/howto/writing-migrations/​.

See also

• The Working with a virtual environment recipe in Chapter 1, Getting Started with Django 3.0
• The Working with Docker containers for Django, Gunicorn, Nginx, and PostgreSQL recipe in Chapter 1, Getting Started with Django 3.0
• The Handling project dependencies with pip receipe in Chapter 1, Getting Started with Django 3.0
• The Including external dependencies in your project recipe in Chapter 1, Getting Started with Django 3.0
• The Changing a foreign key to the many-to-many field recipe