Database Migration with South in Django

If you are a Django programmer and you have not come across 'South' then you have been going through this problem of changing the fields in a model and you just can't run syncdb for that. The only you got is to delete the table schema or the database. If this is your case, you have come to the right place. There is this concept called migration and south does this very well i.e. you don't have to further delete your table schema or database. Lets get quick into it. I will be giving you the shortcut way for migration. For this you don't have to start a brand new project. You can start right away with your existing project. However in this example I will take you with a new project.
First of you need to install south. That's pretty easy with our friendly pip command. So open terminal and hit

pip install south

To verify south is installed. Open interactive python console and try 'import south', if you don't get ImportError then you are ready to go along with me.

So now, Lets create a django project:

django-admin startproject Testsite

This line creates a new project and you will have a directory structure as follows:

TestSite
|
|-manage.py
|-Testsite-|-
|               |-__init__.py
|               |- settings.py
|               |-urls.py
|               |-views.py
|               |-wsgi.py
|

Now Lets create an app.

django-admin startapp post

And the new directory structure will be:

TestSite
|
|-manage.py
|-Testsite-|-
|               |-__init__.py
|               |- settings.py
|               |-urls.py
|               |-views.py
|               |-wsgi.py
|
|-post   -  |-__init_.py
|              |-models.py
|              |-views.py
|              |-tests.py

Ok now, you have successfully created a new app. Lets do some configuration to django project. In Testsite/settings.py change according to your configuration. For me:

DATABASES = {
    'default': {
         'ENGINE': 'django.db.backends.mysql',
        'NAME': 'testsite',              
        'USER': 'root',                  
        'PASSWORD': 'password',              
        'HOST': 'localhost',                
        'PORT': '3306',     }
}

The next thing is to add south and post to INSTALLED_APPS in Testsite/settings.py.
Now run syncdb command: 

./manage.py syncdb

Okay now, lets write our model. Open post/models.py and add these lines

from django.db import models
# Create your models here.
class Post(models.Model):
title=models.CharField(max_length=100)
        description=models.TextField()

And then

 ./manage.py schemamigration post --initial

./manage.py migrate post

Okey this way easy write. Now lets modify our model and add visibility field:

from django.db import models
# Create your models here.
class Post(models.Model):
title=models.CharField(max_length=100)
description=models.TextField()
visibility=models.BooleanField()

Now if we hadn't used south then we had to to either delete the table schema or the database to proceed. But now what you can do is :

 ./manage.py schemamigration post --auto

You'll see:

 ? 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
 ? Please select a choice: 

You choice should be 2 here. And then you'll see :

Please enter Python code for your one-off default value.
 ? The datetime module is available, so you can do e.g. datetime.date.today()
 >>> 

Just type 0 and hit Enter. And you'll see:

 + Added field visibility on post.Post
Created 0002_auto__add_field_post_description__add_field_post_visibility.py. You can now apply this migration with: ./manage.py migrate post

Finally you can do:

./manage.py migrate post

and will see:

Running migrations for post:
 - Migrating forwards to 0002_auto__add_field_post_description__add_field_post_visibility.
 > post:0002_auto__add_field_post_description__add_field_post_visibility
 - Loading initial data for post.
Installed 0 object(s) from 0 fixture(s)

So, the new field has been added to the table schema. Cheers. 

For more you can checkout the documentation page of south at http://south.readthedocs.org/en/latest/genindex.html