Part1:south Foundation

Welcome to the South Tutorial; We will try to introduce the basic use of South and give you some common tips on other things.

If you've never heard of a migration library, you can start by looking at what a migration is, and it can help you better understand South and others, such as django-evolution, to get what you want.

The tutorial assumes that you have correctly installed South, and if not, see the installation instructions.

Begin

In the tutorial, we use migration on a completely new app and describe the process in detail. If there is already an app, don't worry, we'll cover it in the next section.

The 1th thing to notice is that South is available to every application, and that the migration and app code are stored together [1]. If an app does not have any migration definitions, it operates as normal (meaning, using syncdb).

[1] You can put them anywhere you like.

OK, now find a project to work on (or create a new one, set up a database, and more), and we'll build a new app:

./manage.py Startapp Southtut

Typically, a new directory southtut/is generated. Add it to Installed_apps first, then open the new southtu/models.py and create a new model:

From django.db import Modelsclass Knight (models. Model):    name = models. Charfield (max_length=100)    of_the_round_table = models. Booleanfield ()

It's very simple, but effective. Do not use SYNCDB to create a data table for the model in our database, we will generate a migration for it.

1th Migration

There are several ways to create a migration in south: Automatic, Manual. As a starter user, you typically use two automated methods:--initial and--auto.

--auto Check the previous migration to figure out what's changed and generate a migration to apply the difference. If you add a field to the model,--auto will notice this, generate a migration, and create a new column for the field in the table of the model.

Of course, you notice that--auto needs to have a previous migration, and our new app doesn't. So in this case, we need to use--initial to create tables and indexes for all the models in the app; it's the first thing you want to use, more like syncdb, and you can use--auto after each change.

So, let's create a 1th migration:

$./manage.py schemamigration southtut--initialcreating migrations directory at '/home/andrew/programs/litret/ Southtut/migrations ' ... Creating __init__.py in '/home/andrew/programs/litret/southtut/migrations ' ... + Added model Southtut. Knightcreated 0001_initial.py. You can now apply this migration with:./manage.py migrate Southtut

(if it fails, complaining that south_migrationhistory does not exist, you forget to run syncdb after installing south)

As you can see, it creates a migration directory for us and generates a new migration in it. All we need to do is apply our new migration:

$./manage.py Migrate Southtut Running migrations for Southtut:-migrating forwards to 0001_initial. > southtut:0001_initial-loading initial data for Southtut.

In this way, South has created a new table for our model, and if you like can do some checking, use the./manage.py Shell to open the interactive interface and try to add some round Table Knights.

Change model

So far, what we've done is no different from what we can do with syncdb, and it's time to change this (to be exact, our model). Let's add another field to the model:

From django.db import Modelsclass Knight (models. Model):    name = models. Charfield (max_length=100)    of_the_round_table = models. Booleanfield ()    dances_whenever_able = models. Booleanfield ()

Now, if we don't use migrations, showing this new column in our southtu_knight table will be very tiring. With South, however, we only need two simple steps: Generate a migration for the change, and then apply it.

First, create a new migration, using the--auto feature:

$./manage.py schemamigration southtut--auto + Added field dances_whenever_able on Southtut. Knightcreated 0002_auto__add_field_knight_dances_whenever_able.py. You can now apply this migration with:./manage.py migrate Southtut

(Note that South automatically chooses a name for the migration; you can provide it with a custom name as another parameter)

Now, the app changes:

$./manage.py Migrate southtutrunning Migrations for Southtut:-Migrating forwards to 0002_auto__add_field_knight_dances _whenever_able. > southtut:0002_auto__add_field_knight_dances_whenever_able-loading initial data for Southtut.

Immediately, our new column is created. Back to the interactive interface and check that you will be able to add knights, they will dance in the possible time.

Converting an existing apps

Sometimes, especially when you reference a south to a project, you want to use it in existing apps, one of which is that the table has been created.

This situation is different from the new app when you add a migration, and you should read about converting an app to get more information about the operation.

After your pleasant completion of the basic use of South, please move to Part2: Advanced change.

Part1:south Foundation