Add an advanced tutorial on migrations?

Django Internals Documentation
1

I wrote a long blog post that’s supposed to act as a tutorial/how-to of migrations and the pitfalls with them. I think there are some useful bits in it that could be helpful to have in the official documentation.

It’s a bit unique in that it takes users through exception flows rather than how to build something. I think this section and below is what should be considered for being added in. The initial part is more of explanation that I don’t think would be useful.

From a high level the post does the following:

  • Walks the user through how model changes trigger, migrations
  • Shows the user how to view the schema of the database
  • Shows the user how to view the schema changes a migration would make
  • Communicates how your database schema has a separate “state” than your model state"
  • Shows how changing the database and models without changing a migration leads to problems
  • Shows how deleting migration files without cleaning up the database can lead to problems
  • Shows to use the verbosity option on showmigrations to better debug migration problems
  • Shows where the migration application data is stored in the database

It specifically covers/calls out the following:

  • manage.py makemigrations: Creates the migration files
  • manage.py migrate: Runs the migrations (changes the database)
  • manage.py showmigrations --verbosity 2: Tells you what migrations have been applied and when
  • manage.py sqlmigrate <app> <migration>: Tells you what SQL will run for a migration
  • manage.py dbshell: Opens up a database SQL shell
5 Likes
2

Great stuff Tim! I believe this is a specially important knowledge base to be available for newcomers to Django that want to have a deeper knowledge about one of the greatest features of Django.

1 Like