south / docs / convertinganapp.rst

Full commit
Andrew Godwin 4a3aad7 

Andrew Godwin ef8e3fd 

Andrew Godwin 4a3aad7 

Andrew Godwin ef8e3fd 
Andrew Godwin 4a3aad7 

Andrew Godwin ef8e3fd 

Andrew Godwin 4a3aad7 

Luke Plant af0a685 

.. _converting-an-app:

Converting An App

Converting an app to use South is very easy:

 - Edit your and put 'south' into `INSTALLED_APPS`
   (assuming you've installed it to the right place)
 - Run ``./ syncdb`` to load the South table into the database.
   Note that syncdb looks different now - South modifies it.

 - Run ``./ convert_to_south myapp`` - South will automatically make and
   pretend to apply your first migration.

Note that you'll need to convert before you make any changes; South detects
changes by comparing against the frozen state of the last migration, so it
cannot detect changes from before you converted to using South.
Converting other installations and servers

The convert_to_south command only works entirely on the first machine you run it
on. Once you've committed the initial migrations it made into your VCS,
you'll have to run ``./ migrate myapp 0001 --fake`` on every machine that
has a copy of the codebase (make sure they were up-to-date with models and
schema first).

(For the interested, this is required because the initial migration that
convert_to_south makes will try and create all the existing tables; instead, you
tell South that it's already applied using --fake, so the next migrations
apply correctly.)

Remember that new installations of the codebase after this don't need these
steps; you need only do a syncdb then a normal migrate.

If you need to run the migrate command so that it will work for either
situation, you can use ``./ migrate --autofake-first``. For each app
(or each app specified), this will fake the first migration if no migrations
have yet been run for that app and if it detects that at least one table for the
app has already been created.