Context Navigation

About South

South brings migrations to Django applications. Its main objectives are to provide a simple, stable and database-independent migration layer to prevent all the hassle schema changes over time bring to your Django applications.

Overview

Django has always made use of automatic schema generation - the almost-famous "syncdb" that must be run at least once (and often more) on every Django project. If you've ever used Django on a resonably large project, you quickly discover that you're deleting tables and regenerating them if you change schema - and that's only if you're in development, and can afford to possibly lose data.

Other frameworks, such as the infamous Ruby on Rails, have migrations, which incrementally build up a schema as a series of migrations are executed, the idea being that a schema change is simply one more migration. South is an attempt to bring migrations over to Django, but in a more robust and useable way. Read more about it below, or download it and give it a try with our tutorial.

South is currently in beta, and we don't yet have a fully complete database abstraction library. However, the migrations engine is all there, and most database commands are, so give it a go! If you find something missing, tell us about it? (or even better, submit a patch).

The Idea

With South, you install it and then give one or more of your apps some migrations (either writing them by hand, or autogenerating them from your model definitions). When you syncdb, you'll only sync apps that don't have migrations (things like django.contrib.auth, for example, which have a fixed schema), and then when you run ./manage.py migrate, South kicks in and does the migrations. Intelligently.

Missing Migrations

Whereas other, unnamed, migration frameworks often rely on an overall version number for migrations, this suffers with any kind of distributed development; if you write migration #6 and #7, and then apply then, and someone else writes a differently-named migration #6, your system will never know it has another #6 to apply. In South, migrations are tracked individually, and when it detects the migrations have been applied out-of-sequence, it will let you merge them in as you see fit.

Database Independence

Writing raw SQL migrations can be a pain, as you suddenly lose your database agnosticism. South comes with a small database abstraction layer that wraps all of the common table-level functions, and lets you use the Django ORM for any higher-up data moving. We're also on a quest to continually improve the abstraction layer with more functions and databases, so if you want a feature, don't hesistate to ask, or have a go at adding it yourself.

Automatic Migration Creation

While you may find the idea of converting all of your schema into migrations worrying, don't worry - we didn't like the idea either. That's why South not only makes and correctly numbers skeleton migrations for you, it does the same for model definitions, scanning them and writing a complete creation migration for you.