Using South on a Heroku-hosted Django Project

Problem: You need to add new fields to the admin of a Django project hosted on Heroku but don't want to destroy data by running syncdb on your Heroku-hosted database.

Solution: South

These instructions assume you're working in a clean checkout of a Heroku project named herokuproject, which contains a Django project named djangoproject, which contains an app named djangoapp. You need to add a new admin field to djangoapp.

1. Open settings.py and add 'south' to your list of INSTALLED_APPS
2. Run syncdb locally:

   python django_project/manage.py syncdb

3. Convert your project to use South:

   python django_project/manage.py convert_to_south django_app

4. Add some new fields to django_project/django_app/models.py
5. Set up the schema:

   python django_project/manage.py schemamigration django_app --auto

6. Perform the migration:

   python django_project/manage.py migrate django_app

7. Add South Heroku project's requirements.txt file. For example:

   South==0.7.3

8. Add the South django_project/migrations directory to version control and commit all your changes.
9. Push your changes to Heroku:

   git push heroku master

10. Run syncdb on Heroku:

    heroku run bin/python django_project/manage.py syncdb

11. Convert your Heroku instance of django_app to use South

    heroku run bin/python django_project/manage.py convert_to_south django_app

12. Perform the migration:

    heroku run bin/python django_project/manage.py migrate django_app

Note that you will have to repeat the django_app-specific steps for each Django app you modify.

And what if you make further changes to djangoproject/djangoapp/models.py?

1. Make changes to django_project/some_app/models.py
2. Create the south migration file:

   python django_project/manage.py schemamigration some_app --auto

3. Migrate locally:

   python django_project/manage.py migrate some_app

4. Commit your changes and push them to Heroku
5. Migrate on Heroku:

   heroku run bin/python django_project/manage.py migrate some_app

Gratitude to Casey Thomas for the South knowledge-sharing.