.. _migration-structure:

Migration Structure
===================

Migrations are, at the most basic level, files inside your app's migrations/
directory.

When South loads migrations, it loads all the python files inside migrations/
in ASCII sort order (e.g. 1 is before 10 is before 2), and expects to find a
class called Migration inside each one, with at least a ``forwards()``
and ``backwards()`` method.

When South wants to apply a migration, it simply calls the ``forwards()``
method, and similarly when it wants to roll back a migration it calls
``backwards()``. It's up to you what you do inside these methods; the usual
thing is to do database changes, but you don't have to.

Sort Order
----------

Since migrations are loaded in ASCII sort order, they won't be applied in the
correct order if you call them ``1_first, 2_second, ..., 10_tenth``.
(10 sorts before 2).

Rather than force a specific naming convention, we suggest that if you want to
use numerical migrations in this fashion (as we suggest you do) that you prefix
the numbers with zeroes like so: ``0001_first, 0002_second, 0010_tenth``.

All of South's automatic creation code will follow this scheme.

Transactions
------------

Whenever ``forwards()`` or ``backwards()`` is called it is called inside a
database transaction, which is committed if the method executes successfully
or rolled back if it raises an error.

If you need to use two or more transactions inside a migration, either use
two separate migrations (if you think it's appropriate), or have a snippet
like this where you want a new transaction::

    db.commit_transaction()     # Commit the first transaction
    db.start_transaction()      # Start the second, committed on completion

Note that you must commit and start the next transaction if you are making
both data and column changes. If you don't do this, you'll end up with your
database hating you for asking it the impossible.