South Quick Reference

January 23, 2010

South is an excellent database migrations tool for Django.

Converting a Django App to use South

The first step is to convert your application to use South instead of Django's syncdb.

$ ./ convert_to_south app_name

Create a Migration

When you change the model, South can automatically work out the differences between the model and the existing database structure, and generate a migration for you

$ ./ schemamigration app_name reason --auto

See the migrations directory in your application for the new file created.

Run Migration

To run this migration, run the following command:

$ ./ migrate app_name


South records whether a migration has been run or not using the table south_migrationhistory.

id        | integer                  | not null default nextval('south_migrationhistory_id_seq'::regclass)
app_name  | character varying(255)   | not null
migration | character varying(255)   | not null
applied   | timestamp with time zone |

South appears to determine whether your application is enabled for south migrations or not by the presence or absence of the migrations directory inside the application.

Renaming Columns

You can also use south to change the name of a column:

def forwards(self, orm):
    # Rename 'name' field to 'full_name'
    db.rename_column('app_foo', 'name', 'new_name')

def backwards(self, orm):
    # Rename 'full_name' field to 'name'
    db.rename_column('app_foo', 'new_name', 'name')

Tags: django south