How to Use South in Django to Manage Database

Overview

South is a module to help managing database tables when you update models in Django.
Steps to start using South described below.

Described here is case with existing project + database just created + no table created yet
see detail for other cases here >> http://stackoverflow.com/questions/4840102/how-come-my-south-migrations-doesnt-work-for-django

Install South

detail here >> http://south.readthedocs.org/en/0.7.6/
  sudo easy_install South

Initiate South in Legacy Project + No Database

1. add South to INSTALLED_APPS in your settings.py file (not add your application at this step)
2. run python manage.py syncdb
    this will create South table south_migrationhistory in your database.
    skip this step, you will encounter error "Table 'app_name.south_migrationhistory' doesn't exist" when you run command python manage.py migrate app_name in step 5
3. now add your application to INSTALLED_APPS in your settings.py file
4. run python manage.py schemamigration app_name --initial
    this will create initial migration record
5. run python manage.py migrate app_name
If any error occur, you can reset South history as described below.

Reset South History 

detail here >> http://stackoverflow.com/questions/4625712/whats-the-recommended-approach-to-resetting-migration-history-using-django-sout
in case of any error, use following commands

  rm -r appname/migrations/ 
  python manage.py reset south << see NOTE below before run this command
  python manage.py convert_to_south appname 
then drop all related database tables, and initiate South again as described above.
NOTE:
- reset south will delete ALL migration history for all apps that you have installed.
  avoid using this if you only want to remove migration history of some specific app. selectively delete from table south_migrationhistory instead.
  e.g. delete from south_migrationhistory where app_name = 'homepage';
- last command, convert_to_south, use to avoid dropping all your tables. it is equivalent to these two commands
  python manage.py schemamigration --initial app_name_1
  python manage.py schemamigration --initial app_name_2
     ...
  python manage.py migrate --fake

Ongoing Maintenance

after modify models, run following commands
  python manage.py schemamigration app_name --auto
  python manage.py migrate app_name