DjangoPro

Introduction

If you are using Django for production level application, you will need to use south. Requirement changes, and therefore your data model will change over time. South is a great tool, but it is complicated. You do not want to make a mistake when migrating an application in production. This is a detail look at how it interacts with your application so that you can understand and use it better.

Interaction

South interacts (reads and writes) with four different items in an application. This is the most confusing part to me. The four items are:

1. models.py — South reads this to determine your current data model.
2. migrations/*.py — South creates a sub directory inside your app, and creates for you a migration file for each database migration generation. You can also create these by hand, but normally you will let south creates them for you.
3. south_migrationhistory table in your database — when you install south, it creates it’s own table and use it to maintain states. Specifically it records the state of the database in this table. South assumes the application schema in the database is consistent with what it records in this table.
4. your application’s schema in your database — south create and update the schema for you according to the database migration generation, which is the ultimate purpose of using south.

Different commands in south interacts with these items differently:

Normal Migration

Let is start with a normal database schema migration, from generation N to generation N+1. There are three steps in the migration:

1. The developer (you) change the models.py file,
   updating the application's data model.
2. Run manage.py schemamigration app_name --auto to create
   a migration file for generation N+1.
3. Run manage.py migrate app_name to update the database
   schema and migrationhistory table to generation N+1.

This diagram shows what are the inputs and outputs to each step. (Note, in step 2 it reads all of the migration files from all previous generations):

Initial Migration

Let’s add the very first step when using south on a new applicatoin. The initial migration obviously does not have any previous south information. So there are still three steps, but the argument passed to schemamigrate is a little different:

1. The developer (you) creates the first models.py file,
   defining the  application's data model.
2. Run manage.py schemamigrate app_name --initial to
   create a migration  file for generation 1.
3. Run manage.py migrate app_name to create the database
   schema and  migrationhistory table to generation 1.

This diagram shows what are the inputs and outputs to each step, adding to the previous diagram:

Converting an Application

Converting an application is a little different because the database schema and the models are already in sync. Somehow we need to “trick” south into creating the other two items, the migration file and the migrationhistory table entry. We also need to deal with the conversion on the first instance vs other instances differently. For the first instance you will create the migration file, and for all other instances you will use the migration file to simply create the migration history table entry.

On the first app instance:

1. Run manage.py convert_to_south app_name to create the migration
   file for generation 1, and also to create the migrationhistory entry.

On other app instances:

1. Run manage.py migrate app_name 0001 --fake to create
   the migrationhistory without changing the database schema.

Diagram:

Useful Commands

Another useful command is the list command. It shows all the migrations defined in the migration files, and whether they have been applied (by reading the migrationhistory table entries):

manage.py migrate --list

Bonus

This is my initial sketch for my explanation diagrams: