Over the time, the data models and thus the underlying database schema is changing to adapt new features or resolve bugs. Unfortunately Django cannot automatically detect and resolve those changes and upgrade existing instances for us.
To solve this problem, EOxServer uses South for schema and data migration management.
What are migrations?¶
For the uninitiated, migrations (also known as ‘schema evolution’ or ‘mutations’) are a way of changing your database schema from one version into another. Django by itself can only do this by adding new models, but nearly all projects will find themselves changing other aspects of models - be it adding a new field to a model, or changing a database column to have null=True.
—from the South documentation
South needs to be initialized in every instance that wants to make use of the migration features.
Setting up South is quite easy, as all you need to do is install South (most
easy_install), add it to the
settings.py and run
python manage.py syncdb:
INSTALLED_APPS = ( ... 'eoxserver.testing', 'eoxserver.webclient', 'south' )
A complete guide on all installation and configuration options can be found here.
To benefit from South it is important that every change in the data models
concerning the actual database structure is tracked by a migration definition.
Fortunately, for most of the small changes these can be created automatically by
using Souths command
python manage.py schemamigration and passing the
app names which have changes in their models.
A very good tutorial for South can be found here.
Performing a Migration¶
To use South for data migrations only one command needs to be executed:
python manage.py migrate. This applies all necessary database schema changes
to your database and converts all included data from the original schema to the
new one. This command effectively replaces
syncdb (apart from the initial
call to setup South).