Part 1: The Basics

Welcome to the South tutorial; here, we’ll try and cover all the basic usage of South, as well as giving you some general hints about what else to do.

If you’ve never heard of the idea of a migrations library, then please read What are migrations? first; that will help you get a better understanding of what both South (and others, such as django-evolution) are trying to achieve.

This tutorial assumes you have South installed correctly; if not, see the installation instructions.

Starting off

In this tutorial, we’ll follow the process of using migrations on a brand new app. Don’t worry about converting your existing apps; we’ll cover that in the next part.

The first thing to note is that South is per-application; migrations are stored along with the app’s code [1]. If an app doesn’t have any migrations defined, South will ignore it, and it will behave as normal (that is, using syncdb).

[1]You can also store them elsewhere if you like.

So, find a project to work in (or make a new one, and set it up with a database and other settings), and let’s create our new app:

./manage.py startapp southtut

As usual, this should make a new directory southtut/. First, add it to INSTALLED_APPS, then open up the newly-created southtut/models.py, and create a new model:

from django.db import models

class Knight(models.Model):
    name = models.CharField(max_length=100)
    of_the_round_table = models.BooleanField()

It’s quite simple, but it’ll do. Now, instead of running syncdb to create a table for the model in our database, we’ll create a migration for it.

The First Migration

South has several ways of creating migrations; some are automatic, some are manual. As a basic user, you’ll probably use the two automatic ways - --auto and --initial.

--auto looks at the previous migration, works out what’s changed, and creates a migration which applies the differences - for example, if you add a field to a model, --auto will notice this, and make a migration which creates a new column for that field on its model’s table.

However, you’ll notice that --auto needs a previous migration - our new app doesn’t have one. Instead, in this case, we need to use --initial, which will create tables and indexes for all of the models in the app; it’s what you use first, much like syncdb, and --auto is then used afterwards for each change.

So, let’s create our first migration:

$ ./manage.py schemamigration southtut --initial
Creating migrations directory at '/home/andrew/Programs/litret/southtut/migrations'...
Creating __init__.py in '/home/andrew/Programs/litret/southtut/migrations'...
 + Added model southtut.Knight
Created 0001_initial.py. You can now apply this migration with: ./manage.py migrate southtut

(If this fails complaining that south_migrationhistory does not exist, you forgot to run syncdb after you installed South.)

As you can see, that’s created a migrations directory for us, and made a new migration inside it. All we need to do now is apply our new migration:

$ ./manage.py migrate southtut
 Running migrations for southtut:
 - Migrating forwards to 0001_initial.
 > southtut:0001_initial
 - Loading initial data for southtut.

With that, South has created the new table for our model; check if you like, and try adding a few Knights using ./manage.py shell.

Changing the model

So far, we’ve done nothing that syncdb couldn’t accomplish; time to change that (or rather, our model). Let’s add another field to our model:

from django.db import models

class Knight(models.Model):
    name = models.CharField(max_length=100)
    of_the_round_table = models.BooleanField()
    dances_whenever_able = models.BooleanField()

Now, if we weren’t using migrations, making this new column appear on our southtut_knight table would be annoying at best. However, with South, we need only do two, quick steps: make a migration for the change, then apply it.

First, make the new migration, using the –auto feature:

$ ./manage.py schemamigration southtut --auto
 + Added field dances_whenever_able on southtut.Knight
Created 0002_auto__add_field_knight_dances_whenever_able.py. You can now apply this migration with: ./manage.py migrate southtut

(Notice that South has automatically picked a name for this migration; you can instead give migrations custom names by providing it as another argument)

Now, apply it:

$ ./manage.py migrate southtut
Running migrations for southtut:
 - Migrating forwards to 0002_auto__add_field_knight_dances_whenever_able.
 > southtut:0002_auto__add_field_knight_dances_whenever_able
 - Loading initial data for southtut.

With that, our new column is created; again, go and check, you’ll be able to add Knights who can dance whenever they’re able.

Converting existing apps

Sometimes, especially when introducting South into a project, you will want to use it for existing apps - ones for which the tables have already been created.

This is different from adding migrations to an all-new app, and you should see the Converting An App page for more information on how to do it.

Once you’re happy with this basic usage of South, move on to Part 2: Advanced Changes.

Table Of Contents

Previous topic

Tutorial

Next topic

Part 2: Advanced Changes

This Page