1. Igor Guerrero
  2. south


south / docs /

Filename Size Date modified Message
508 B
399 B
8.9 KB
6.4 KB
3.1 KB
This is South, a Django application to provide migrations in a sane way.

By sane, we mean that the status of every migration is tracked individually,
rather than just the number of the top migration reached; this means South
can detect when you have an unapplied migration that's sitting in the middle
of a whole load of applied ones, and will let you apply it straight off,
or let you roll back to it, and apply from there forward.


If you have any problems with South not addressed in this documentation, or
would like to request a feature, please get in touch with me at
andrew at aeracode dot org.

More up-to-date news and docs on South can be found at



Simply make sure the south directory is in your python path; you can
refer to how Django does this, at:


Then, stick 'south' in your INSTALLED_APPS setting, and run ./manage.py syncdb
(which will look a little different to normal, as you'll now have the South

Note that South requires a reasonably new version of Django; we're running it
against 1.0 alpha, but it should work on 0.97-pre-svn too.


You'll interact with South in two main ways; via manage.py, and through
app migrations.

 South has three commands in manage.py:
  syncdb - This is a modified version of the original Django syncdb, that
           only does the usual syncdb on apps without migrations (i.e. without
           a migrations/ python package in their app directory).
           This means you can still use syncdb's magic creation for things like
           Django auth, but use migrations for your own app.

  migrate - Allows you to migrate forwards or backwards. With no arguments,
            will migrate forwards as far as it can (i.e. perform all migrations).
            If you provide an argument, it will attempt to migrate forwards
            or backwards until it reaches the state where it would have just
            performed the named migration (e.g. ./manage.py migrate 0002_test)
            If you only provide the first part of a name (e.g. 0002), South will
            use the migration with that prefix (if there is only one). If there
            are multiple matching migrations, or no matching migrations, South
            will complain and you'll have to type more of the name (or fix
            your spelling).
            This argument does not end in .py, and you can use the special
            argument 'zero' to undo every single migration.
            If there is a consistency error - that is, South finds a migration
            which is unapplied, but before a migration that is already applied -
            it will tell you what migrations are wrong and refuse to continue.
            In this situation, you need to provide one of these command-line
             --skip will ignore any warnings and just continue applying
                    or undoing migrations.
             --merge will run the missing migrations straight away, and then
                     continue, if you are trying to progress forwards. If you
                     are trying to migrate backwards, it behaves like --skip.
            Generally, a sensible thing to do is either --merge, or perform
            a rollback to the offending migration and then roll forwards.
            For example, if 0003_addedlater is the unapplied migration:
              ./manage.py migrate --skip 0002_test
              ./manage.py migrate
            Here, we roll back past where 0003 would have been applied and
            then roll forwards, applying it in the process.
            There is also this command-line switch:
             --fake will pretend to do the migrations, change the migration
                    record to say they have been done/undone, but won't actually
                    run them. This is most useful when your database is already
                    at some migrated point, but the migrations table doesn't
                    know about it.

  startmigration - Provide this command with an app name and optional migration
                   name and it will create a new stub migration for you.
                   If the app currently has no migration directory, it will
                   also create that.
                   If you also provide a model name for the app as a third
                   argument, it will scan that model and automatically generate
                   a migration to create it as it currently is; this hopefully
                   will ease the loss of syncdb. Be aware you may have to make
                   sure the migrations are manually in the correct order if your
                   database enforces foreign key dependencies strongly (although
                   they should generally work, as they're deferred by default).
                   If you pass the commandline switch --all with no migration or
                   model name it will create migrations for each model in the
                   given app (this should be used for kickstarting new projects)

 Migrations are found in the migrations/ directory under an app. They are always
 executed in ASCII sort order, so 11_foo.py would be executed before 2_bar.py
 (you can get around this by naming files like 0002_bar.py; this is what
 ./manage.py startmigration does).
 Inside a migration file, there should be a Migration class with forward() and
 backward() methods. These will be called when the migration needs to be executed
 in the respective directions.
 You can do anything inside these two functions; you can use the Django ORM
 to change data, or django.db.connection to execute raw SQL, for example.
 However, as raw SQL isn't very portable, there's also a thin database actions
 abstraction layer called south.db.db, which provides database-agnostic
 methods like create_table, add_column, rename_column, and so on.
 Documentation for south.db can be found in the db.txt file in the docs/ directory.
 South is released under the Apache Public License, version 2. A copy of
 this license can be found in the file docs/LICENSE, or at