Django schema migration using South
Over the developing period of Django web application the models change a lot. Managing these changes in a team environment working on a Django project can become complicated. Unfortunately Django doesn’t capture the changes in the existing models. Until Django will provide an solution to this problem, you will need to use a schema migration tool. After I have browsed for such tools, I decided to use South. This post will explain how to use South.
Install South and verify that ‘south’ entry is added to INSTALLED_APPS in settings.py file. Run manage.py syncdb to create the South migration history table for the first time.
D:\NetBeansProjects\ProjectX\src\project>python manage.py syncdb
Syncing...
Creating table south_migrationhistory
Synced:
> django.contrib.auth
> django.contrib.contenttypes
> django.contrib.sessions
> django.contrib.admin
> project.login
> project.customer
> project.utils
> south
Not synced (use migrations):
-
(use ./manage.py migrate to migrate these)
Create an initial migration for the application. Application means an entry from INSTALLED_APPS of settings.py file(for example: project.customer). This yields a migration that matches the existing database schema.
D:\NetBeansProjects\ProjectX\src\project>python manage.py schemamigration project.customer --initial
Creating migrations directory at 'D:\NetBeansProjects\ProjectX\src\project\..\project\cust
omer\migrations'...
Creating __init__.py in 'D:\NetBeansProjects\ProjectX\src\project\..\project\customer\migr
ations'...
+ Added model customer.Booking
+ Added unique constraint for ['booking_date', 'booking_number'] on customer.Bo
oking
+ Added model customer.Address
Created 0001_initial.py. You can now apply this migration with: ./manage.py migr
ate project.customer
The next step is to bring the application under South’s control.
D:\NetBeansProjects\ProjectX\src\project>python manage.py migrate project.customer 0001 --fake
- Soft matched migration 0001 to 0001_initial.
Running migrations for customer:
- Migrating forwards to 0001_initial.
> customer:0001_initial
(faked)
The previous steps were necessary only once for setting South for the first time. Then after every change to the models the command schemamigration is used to generate a migration for the new models and fields. This example will add a new field test to the Booking model.
D:\NetBeansProjects\ProjectX\src\project>python manage.py schemamigration project.customer
--auto
? The field 'Booking.test_field' does not have a default specified, yet is NOT
NULL.
? Since you are adding or removing this field, you MUST specify a default
? value to use for existing rows. Would you like to:
? 1. Quit now, and add a default to the field in models.py
? 2. Specify a one-off value to use for existing columns now
? Please select a choice: 2
? Please enter Python code for your one-off default value.
? The datetime module is available, so you can do e.g. datetime.date.today()
>>> "test"
+ Added field test_field on customer.Booking
Created 0002_auto__add_field_booking_test_field.py. You can now apply this migra
tion with: ./manage.py migrate project.customer
Now, apply the migration:
D:\NetBeansProjects\ProjectX\src\project>python manage.py migrate project.customer
Running migrations for customer:
- Migrating forwards to 0002_auto__add_field_booking_test_field.
> customer:0002_auto__add_field_booking_test_field
- Loading initial data for customer.
For further information see:
South documentation
Django documentation
Tags: database django PostgreSQL Python schema evolution schema migration south
Posted in: Software Development
July 30, 2010
| 
Ioan Seicean | 
One Comment
One Response
September 21, 2010 1
Pretty nice post. I just stumbled upon your blog and wanted to say that I have really enjoyed browsing your blog posts. In any case I’ll be subscribing to your feed and I hope you write again soon!
Leave a Reply