Converting An App
Converting an app to use South is very easy:
- Edit your settings.py and put 'south' into INSTALLED_APPS (assuming you've installed it to the right place)
- Run ./manage.py syncdb to load the South table into the database. Note that syncdb looks different now - South modifies it.
If you're running 0.6:
- Run ./manage.py convert_to_south myapp - South will automatically make and pretend to apply your first migration.
If you're running 0.5:
- Run ./manage.py startmigration myapp --initial - this will create a migrations directory and a first migration that will create the schema you currently have in models.py.
- Run ./manage.py migrate myapp to use South to make the tables. If you've already syncdb'd this app, you can run ./manage.py migrate myapp --fake to trick South into thinking the migrations are already applied (the tables are created, so technically they are, it's just that South didn't make them so it needs informing)
Converting other installations and servers (both versions)
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 the database, you'll have to run an extra step on every machine that has a copy of the codebase (make sure they were up-to-date with models and schema first):
- Run ./manage.py migrate myapp 0001 --fake on each other install to inform South that their databases already match the results of the first migration.
- Remember that new installations of the codebase after this don't need these steps; you need only do a syncdb then a normal migrate.