Django is well known for being a super fast development framework for people with short deadlines.

However having short deadlines means that you sometimes make mistakes when it comes to configuring a database structure, or you might forget a column that should have been in the table.

Traditionally you have to go do python manage.py dbshell and then manually edit it by hand.

This can be a long and tedious way of doing it and not always the right result.

Now with South all you need to do is drop South into your root folder where Django resides and follow these instructions:

Make sure the south/south/ directory is in your python path – just like you did with Django when you installed it – and then add ‘south’ to your INSTALLED_APPS setting. You can do this either by extending your python path (append to sys.path), or by running python setup.py install in the South directory.

Note that the south application is in the “south” subdirectory of trunk, so you’ll have to add the directory you check out to the path, not its parent.

Run ./manage.py syncdb (taking notice of the new migration-enabled syncdb) and you’re ready to go!

class Poll(models.Model):
    question = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')

class Choice(models.Model):
    poll = models.ForeignKey(Poll)
    choice = models.CharField(max_length=200)
    votes = models.IntegerField()

Once this is done, run an initial migration to see what the app looks like from the beginning.

$ ./manage.py startmigration polls --initial
Creating migrations directory at '/Users/arnosmit/lib/django-test-utils/test_project
/polls/migrations'...
Creating __init__.py in '/Users/arnosmit/lib/django-test-utils/test_project/
polls/migrations'...
 + Added model 'polls.Poll'
 + Added model 'polls.Choice'
Created 0001_initial.py.

Once you have done this you might want to add or remove a field from your model to see the effect.

class Poll(models.Model):
    question = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')
    slug = models.SlugField(null=True)

Run the migration statement

$ ./manage.py startmigration polls add_slug --auto
 + Added field 'polls.poll.slug'
Created 0002_add_slug.py.

$ ./manage.py migrate polls 0001
 - Soft matched migration 0001 to 0001_initial.
Running migrations for polls:
 - Migrating forwards to 0001_initial.
 > polls: 0001_initial
   = CREATE TABLE "polls_poll" ("id" integer NOT NULL PRIMARY KEY, "question"
varchar(200) NOT NULL, "pub_date" datetime NOT NULL); []
   = CREATE TABLE "polls_choice" ("id" integer NOT NULL PRIMARY KEY, "poll_id"
integer NOT NULL, "choice" varchar(200) NOT NULL, "votes" integer NOT NULL); []
   = CREATE INDEX "polls_choice_poll_id" ON "polls_choice" ("poll_id"); []
 - Sending post_syncdb signal for polls: ['Poll']
 - Sending post_syncdb signal for polls: ['Choice']