Blog Posted February 18, 2012

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.