Autodetection

Please note: This is covered in Tutorial, Part 2 as well.

For quite a while, South was manual-only; you had to create migrations by hand. Then, the startmigration command was introduced, which automated the writing of some common migrations - such as adding new models or fields - but you still had to manually say what actions the migration should perform.

Now, as of South 0.5, there is autodetection of most changes to models.py; specifically:

• Adding and removing models
• Adding and removing fields from a model
• Changing a field on a model (only some attributes support changing)
• Changing the unique_together attribute in a model's Meta
• South cannot detect renaming of fields or models. It will think it is a deletion and creation; in future, the command will interactively ask you what it is.

Enabling

An autodetection-friendly set of migrations in South is entirely optional, and must be explicitly enabled - autodetection requires that the entire app be frozen into every migration, and so it can lead to clutter.

To use autodetection, you will need to have at least one migration, and you must not have set SOUTH_AUTO_FREEZE_APP = False in your settings.py. (Don't worry, you probably haven't.)

If you've previously not frozen the models.py into every migration, don't worry - only the most recent migration needs to have one. If needed, you can just create a blank (no actions) migration with only the frozen state with

./manage.py startmigration appname auto_start --freeze appname

(here auto_start is the name of the migration, and can be replaced with anything)

If you try to use the autodetector without the right environment, South will usually tell you explicitly why it's failed.

Usage

Once you have a previous migration with the app state frozen, you can then edit the models.py and make some changes. Once you're ready to make a migration that saves what you've done, run

./manage.py startmigration appname --auto

South will then attempt to determine what's changed, and spit out a new migration for you. It will warn you of anything it knows has changed but which it can't fix (yet).

Bugs

Since this is a new feature, there may be some bugs - we advice you always to check the created file (as you should anyway), and if you do find autodetection to not be working as intended, plaese submit a bug report.