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.
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 . If an app doesn’t have any migrations defined, South will ignore it, and it will behave as normal (that is, using syncdb).
|||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
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 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
will create tables and indexes for all of the models in the app; it’s what you
use first, much like
--auto is then used afterwards for
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
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.