Django Migrations

Nate Robison (@NTRobison)
march 13th, 2015

The recent release of Django 1.7 comes with built-in support for database migrations. In previous versions of Django, the popular way to manage migrations was a third-party tool called South. Thanks to a successful Kickstarter project, the creator of South worked to build support for migrations into Django 1.7.

Why is this a big deal?

You might be wondering why you should care about Django now having built-in migrations. There are a few reasons:

  1. Easier version control of database changes.

    The way Django creates migrations allows change tracking. Any time a migration is created and applied, it is stored in numerical order with the changes in a .py file with standard formatting. That means that it is much easier to track when, where, and what has been changed, all using your existing source control system.

  2. Quick and easy changes.

    Migrations allow quicker and easier modification of an existing schema without the hassle of dropping and re-creating tables. This is very important if there is data that must not be lost when a schema change is required.

  3. Avoid SQL (unless you like that kind of thing).

    Using SQL with Django is acceptable but thanks to migrations there is no need to maintain SQL scripts. The built-in migrations will generate and execute the correct SQL based on which database engine you use.

It’s Python therefore it’s easy right?


The built-in migration tools make it very easy to create and execute the migrations. Let’s assume you have a brand new project and have yet to run the syncDB command to automatically create the database schema. Using the command line, navigate to the project’s root directory. Then: makemigrations [Optional App Name here]

Using the above command will create the initial migrations. If you do not include an app name, Django will create an initial migration for all apps within the project.

Then, apply the migration by running the following command: migrate [Optional App Name here]

This will look within the migrations directory to apply any new modifications. If an app name is provided, Django will apply the migrations only for that app.

That’s all. You have applied your migrations and made changes to the schema.

What if I have an existing project or have used South?

The steps for creating migrations for an existing project or a project using South are almost the same as above. If you have an existing project, follow these simple steps to start using migrations. For detailed instructions about moving from South to Django migrations see the Django Documentation.

  1. If you previously used South, delete any South migrations, or move them to a new directory.

  2. Make the initial migration: makemigrations

    This will create migrations for all apps within the project.

  3. “Apply” the migrations: migrate

This will allow Django to see that the tables already exist and mark the migration as complete.

That’s it! You have moved to adopted Django migrations and can now use migrations anytime you need to change the database schema. This means editing models and the corresponding database is quick and painless.


If you are using Django and not using migrations or South, then you should really consider upgrading to 1.7. The built-in migrations are very powerful and extremely useful when dealing with database schema changes. These migrations can be done with two simple commands that create and execute most changes. It doesn’t get much easier than that. It even properly handles foreign keys. Check out the Django 1.7 release notes to find out what other great features have been added.

Tags: technology python django