Version 3 (modified by andrew, 7 years ago) (diff)


Command Reference

South is mainly used via the console and its two important commands: migrate and startmigration.


The migrate command is used to control the migration of the system forwards or backwards through the series of migrations for any given app.

The most common use is:

./ migrate myapp

This will migrate the app myapp forwards through all the migrations. If you want to migrate all the apps at once, run:

./ migrate myapp

This has the same effect as calling the first example for every app, and will deal with Dependencies properly.

You can also specify a specific migration to migrate to:

./ migrate myapp 0002_add_username

Note that, if the system has already migrated past the specified migration, it will roll back to it instead. If you want to migrate all the way back, specify the special migration name zero:

./ migrate myapp zero

You can also just give prefixes of migrations, to save typing:

./ migrate myapp 0002

But they must be unique:

$ ./ migrate myapp 000
Running migrations for myapp:
 - Prefix 00 matches more than one migration:

Conflict Resolution

South's migration system really comes into its own when you start getting conflicting migrations - that is, migrations that have been applied in the wrong sequence.

One example is if Anne writes new migrations 0003_foo and 0004_bar, runs the migration up to 0004 to make sure her local copy is up-to-date, and then updates her code from (say) Subversion. In the meantime, her coworker Bob has written a migration 0003_baz, which gets pulled in.

Now, there's a problem. 0003_phou should have been applied before 0004_bar, but it hasn't been; in this situation, South will helpfully say something like

Running migrations for aeblog:
 - Current migration: 5 (after 0004_bar)
 - Target migration: 5 (after 0004_bar)
 ! These migrations should have been applied already, but aren't:
   - 0003_phou
 ! Please re-run migrate with one of these switches:
   --skip: Ignore this migration mismatch and keep going
   --merge: Just apply the missing migrations out of order
   If you want to roll back to the first of these migrations
   and then roll forward, do:
     ./ migrate --skip 0002_add_username
     ./ migrate

As you can see, you have two real options; --merge, which will just apply the missing migration and continue, and the two commands which roll back to before the missing migration (using --skip to ignore the error we're dealing with) and then migrating properly, in order, from there to the end.

Using --skip by itself will let you continue, but isn't much of a solution; South will still complain the next time you run a migrate without --skip.

Sometimes, even worse things happen and South finds out that an applied migration has gone missing from the filesystem. In this scenario, it will politely tell you to go fix the problem yourself.


While migrate is the real meat and bones of South, startmigration is by comparison an entirely optional extra. It's a utility to help write some of your migrations (specifically, the ones to create tables for new models) for you; if you like, you can ignore it and write everything youself, in which case we wish you good luck, and happy typing.

However, if you have a sense of reason, you'll realise that having the skeletons of migrations and the whole of model creation migrations created for you is really Quite Handy.

The main use of startmigration is when you've just finished your shiny new and want to load up your database. In vanilla Django, you'd just run syncdb - however, with migrations, you'll need a migration to create the tables.

In this scenario, you just run:

./ startmigration myapp --initial

That will write one big migration to create all the tables for the models in your app; just run ./ migrate to get it in and you're done in only one more step than syncdb!

Later on, you'll add models to your app; to create migrations for individual models, simply run

./ startmigration myapp two_new_models --model Foo --model Bar

Here, we create a migration called 0002_two_new_models (or a higher number - South picks the next available one) which will create the tables for the models Foo and Bar.

Finally, if you're writing a migration for new fields on an existing model (some add_column calls) or something else that isn't a whole new model creation, then you can just create a skeleton:

./ startmigration myapp my_new_column_migration

The skeleton looks something like this:

from south.db import db
from myapp.models import *

class Migration:
    def forwards(self):
        "Write your forwards migration here"
    def backwards(self):
        "Write your backwards migration here"