Using South for schema and data migrations in Django
How to keep you database up to date with model changes in your app
South is a schema and data migrations for Django. In an easy way you may update your database tables after you change your models. It also keeps all migrations in the codebase allowing to migrate backward if needed. In this article I'll show some standard South usage cases.
Installing and configuring SouthThe quickest way to install south is to use pipL
Basic usageWithout south you would use syncdb to create table of your new models. When using south you create migrations to do all the database work, including the initial migration creating tables:
In this example south will do everything on its own and we can just execute the migration.
Now lets try a field that can't be empty:When you try creating a migration south will ask:
? The field 'MyModel.number' does not have a default specified, yet is NOT NULL. ? Since you are adding this field, you MUST specify a default ? value to use for existing rows. Would you like to: ? 1. Quit now, and add a default to the field in models.py ? 2. Specify a one-off value to use for existing columns now
You can choose 1 and quit (and then for example add default to the field) or use 2 and provide a default value for the migration (value used only for entries existing at the time of migration).
Data migrationsWhat if we would want to add a unique field to a table with existing entries?: You can't make a unique column with bunch of existing entries having a Null value. At start we have to make a field that allows null values (they won't count for the unique constraint):
The plan is simple - we create such column (migration), then we do a data migration (we make unique values for the existing entries) and in the end we remove the null with another schema migration.To make an empty data migration use this:
The forwards method is used to make the migration. backwards is used to do a backward migration (if it's something complex/non reversible you can disable it). The key element is to write the migration.Here is a simple example providing unique values for the slug column (we could use Django slugify helper and some unique value generators, but this is just an example): You execute data migrations just like schema migrations.
Backward migrationsSouth allows backward migrations. You can migrate to an older migration by specifying its number:
Dependencies for migrations
In some cases when you have migrations covering model/database relations there may be a problem with the order in which migrations are executed. The migration with the relation may try to execute before the related table will be created by another migration. To apply correct order we can use "depends_on" in the migration class:
Such problems may show up during tests or build processes where everything is created from scratch.You will find more in the south documentation.