Django South is a useful database migration tool for Django projects. It allows you to make changes to your models and automatically generate migrations to update your database schema. However, you may encounter frustrating “table already exists” errors when running these migrations. In this post, we’ll explore some common causes and solutions for these errors.

Understanding Django South Migrations

First, let’s review how South migrations work. When you install South in an existing Django project, it creates an initial migration representing your current database structure. From then on, any changes you make to your models can be converted into a new migration script that South can run to alter the database.

However, if you create a new empty migration and try to run it when no changes were made, South doesn’t know what to change in the database. As a result, it tries creating all your tables again from scratch, even though they may already exist, resulting in “table already exists” errors.

Forgetting to Commit Model Changes

One common slip-up is changing your models but forgetting to create and commit a migration before running migrate. For example, you may tweak a model field then immediately run migrate, only to find South doesn’t know what model change you want to apply.

Always be sure to generate and commit migrations between any model changes and running database updates. The workflow should go:

Edit models.py
Run ./manage.py schemamigration myapp --auto
Run ./manage.py migrate myapp

Following this consistent process will ensure South stays in sync with your models and avoids unnecessary errors.

Deleting Migration History – Django South

South stores migration history in the Django database itself, so it knows which migrations have already been applied. If this history gets deleted accidentally, South no longer knows the state of the database, which can again lead to frustrating table creation errors.

The safest approach is to never manually delete South’s internal tables (named south_migrationhistory by default). If they do get deleted, the easiest recovery is to comment out all model changes and re-run the initial migration. This will repopulate South’s history without making unnecessary database alterations.

Altering Underlying Tables

For various reasons, developers sometimes bypass South migrations and directly execute SQL commands to alter, delete, or recreate underlying database tables. However, South still believes those tables match what it expects from the migration history. When new migrations try to recreate these modified tables, collisions occur.

To avoid such issues, try to always stick to proper South migrations for any schema changes. If manual SQL alterations do occur, the fix is to edit the migration history to match the current state of the database before adding any new migrations. This keeps South’s history consistent.

Running Migrations Out of Order

Another source of “table already exists” errors is running old migrations on a database that already has a newer schema. For example, a migration that creates table X may have already run successfully. But if an old migration that creates the same table X is accidentally applied again, it will fail because the table now exists.

The best way to avoid this is committing your migrations in order and not reverting to old migration states unless absolutely necessary. South allows jumping around history, but do so carefully to prevent migration collisions.

Solutions and Preventative Measures

In summary, here are some tips to prevent these errors when using South:

Always commit model changes before running migrations
Don’t manually delete the migration history tables
Use South migrations for all schema changes – don’t use direct SQL
Review migration history for inconsistencies after manual SQL alterations
Be cautious about running old migrations on an updated database

While these South errors can be annoying to debug, following best practices around consistent migration workflows will allow you to benefit from South’s excellent schema management capabilities and avoid wasted time troubleshooting avoidable issues.

Conclusion

Django South provides a huge productivity boost for evolving database schemas under active development. However, developers may encounter confusing “table already exists” errors if the migration history becomes out of sync with the real state of the database. By understanding what causes these inconsistencies and sticking to consistent migration practices, you can comfortably utilize South for all your database migration needs.

The key points to remember are committing all model changes first, not tampering with South’s history tables, using South commands exclusively for all schema changes, and applying migrations in sequential order. Following these guidelines will help you harness South’s capabilities for streamlined database management in Djang o.