South Help

From NovaWebDev Wiki
Jump to: navigation, search

One could always follow the south tutorial, http://south.readthedocs.org/en/latest/tutorial/part1.html, but we're going to outline the steps we took to add south to an existing project as that is the most common use case.

Add south to requirements.txt, assuming in our case that we are using Django 1.5. Also, update the INSTALLED_APP list in settings.py with the south app. You will need to run the pip install (make sure your virtual environment is active!)

edit requirements.txt to add
    South==0.8.2
pip install -r requirements.txt (will add south package to virtual environment, again be sure it's active)
edit settings.py to add in INSTALLED_APPS
    'south',

Now we want to actually apply the south package to our app, assuming we have just the one app, call it my_app. We need to first do a syncdb to get south into our database, and then we create out initial migration for my_app. After running the convert_to_south command, we see that a migrations directory is created in the my_app directory with an initial 0001_initial.py file that contains the migration code for getting to the initial south state. This would be a good time to add that directory to the code repository and commit.

python manage.py syncdb
python manage.py convert_to_south my_app
(if all went well)
git commit -a
git push 

Before we get into making a change that needs a new south migration, now would be a good time to go to the other places you have the app installed (production instances, for example) and, after pulling the new code from the repository, run the initial migration with the south's fake command. We need to so a syncdb first to get the south table into the database.

go to production server and pull code from repository
    cd /path/to/site/that/uses/my_app
    git pull (if using git)
    pip install -r requirements.txt (will add south package to virtual environment, again be sure it's active)
python manage.py syncdb (make sure virtual environment is activated)
python manage.py migrate my_app 0001 --fake

We are ready to make our first change to the model that will necessitate the use of south. Pick a field in your my_app model and change it to have a different length, or add a new field to the model. The idea is that you make a change that you can't apply with syncdb. After you have made the change, run the following commands.

edit my_app/models.py
    change or add some field that needs to be southified
python manage.py schemamigration my_app --auto
python manage.py migrate my_app

After committing and pushing the code changes (don't forget to git add the new migration file created during the schemamigration command), go to the production server and apply the migration there.

go to production server and pull code from repository
    cd /path/to/site/that/uses/my_app
    git pull (if using git)
activate the virtual environment
python manage.py migrate my_app

Note that you don't need to restart the server for the database changes to take effect in the database itself as the migrate command already does that for us. However, if you have forms that are effected by your model change, then you'll have to restart. In short, it's probably best to always restart the server as you do anyway when you pull code to a production instance, but it's not necessary for the database changes to happen.

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox