South チュートリアルへようこそ; ここでは South の基本的な使用方法をカバーするだけでなく、また違う方法についての一般的なヒントも提供しています。
もしマイグレーションライブラリの概念について聞いたこともない場合には マイグレーションとは？ をまずお読み下さい; South (と django-evolution のような他のアプリ) が実現しようとしていることを理解する助けにもなるはずです。
このチュートリアルは South を既に正しくインストールしていることを前提としています; もしまだインストールしていなければ インストールについての説明 をご覧下さい。
このチュートリアルでは、新規アプリケーションにマイグレーションを適用していく過程を追っていきます。 既存のアプリを変換したい場合も心配はいりません; ちゃんと次の章で説明します。
最初に注意すべきは、South は各アプリケーションを対象に動作するという点です; マイグレーションはアプリのコードと一緒に保存されます [1] 。 アプリにマイグレーションが定義されていない場合、South はそのアプリを無視して、標準の(つまり syncdb を使用した)処理を行います。
| [1] | お望みならば マイグレーションを他の場所に保存する ことも可能です。 |
それでは South を組込むプロジェクトを見つけて(もしくは新規に作成して、データベースやその他の設定を行なって下さい) [*] 、 新しいアプリを作成しましょう:
./manage.py startapp southtut
| [*] | 訳注: ここで south_migrationhistory テーブルを作成するため、South 導入プロジェクトに対する syncdb が必要なはず |
ここで、いつものように新しく southtut/ ディレクトリが作成されます。 まずは INSTALLED_APPS にアプリを追加して、次に southtut/models.py を開き、新しいモデルを作成します:
from django.db import models
class Knight(models.Model):
name = models.CharField(max_length=100)
of_the_round_table = models.BooleanField()
シンプル過ぎますが、これだけで十分でしょう。 さて、データベースにモデルのテーブルを作るため syncdb を走らせるかわりに、 マイグレーションを作成しましょう。
South にはマイグレーション生成の方法がいくつか; 自動的な方法も、手動で行う方法もあります。 基本的には、ふたつの自動的な方法 - --auto と --initial を使えばいいでしょう。
--auto は前回のマイグレーションを見て、何が変更されたのかを割り出し、 差分を適用するマイグレーションを生成します - 例えば、あるモデルにフィールドを追加した場合、 --auto はこの変更を検知して、追加フィールド用の新しいカラムを、 そのモデルのテーブルに追加するようなマイグレーションを生成します。
--auto には前回のマイグレーションが必要、ということがわかったと思いますが、 新規作成したアプリにはまだマイグレーションがありません。 その代わり、この場合には、アプリ内の全モデルのテーブルとインデックスを生成する --initial を使う必要があります; syncdb と同じように、まず最初にこれを使えば、それ以降の --auto はその前のマイグレーションを使用します。
では、最初のマイグレーションを作りましょう:
$ ./manage.py schemamigration southtut --initial
Creating migrations directory at '/home/andrew/Programs/litret/southtut/migrations'...
Creating __init__.py in '/home/andrew/Programs/litret/southtut/migrations'...
+ Added model southtut.Knight
Created 0001_initial.py. You can now apply this migration with: ./manage.py migrate southtut
ご覧のように、migrations ディレクトリが作られて、その下に新しいマイグレーションが生成されました。 次に、この新しくできたマイグレーションを適用しましょう:
$ ./manage.py migrate southtut
Running migrations for southtut:
- Migrating forwards to 0001_initial.
> southtut:0001_initial
- Loading initial data for southtut.
これで South は Knight モデル用の新しいテーブルを作成しました; よければ ./manage.py shell を使って確認したり、いくつか Knight を追加してみて下さい。
今までのところ syncdb でできることしかやっていません; そろそろモデルの変更をしていきましょう。 では、モデルにもうひとつフィールドを追加してみます:
from django.db import models
class Knight(models.Model):
name = models.CharField(max_length=100)
of_the_round_table = models.BooleanField()
dances_whenever_able = models.BooleanField()
さて、マイグレーションが無ければ、 southtut_knight テーブルに新しいカラムを追加するのは、 どれだけ贔屓目に見ても、面倒な作業でしかありません。しかし South を使っていれば、やることは たった 2 ステップだけです; 今回の変更に対するマイグレーションの作成と、その適用です。
まず --auto 機能で新しいマイグレーションを作ります:
$ ./manage.py schemamigration southtut --auto
+ Added field dances_whenever_able on southtut.Knight
Created 0002_auto__add_field_knight_dances_whenever_able.py. You can now apply this migration with: ./manage.py migrate southtut
(South は自動的にマイグレーション名を選定する点に注意して下さい; 引数に渡すことで、カスタムマイグレーション名を指定することもできます)
次に、これを適用しましょう:
$ ./manage.py migrate southtut
Running 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.
これで新しいカラムが作成されました; 再度確認してみましょう。 dances_whenever_able フィールドを持つ Knight を追加することができると思います。
ここまでで South の基本的な使用法がわかったので Part 2: 高度な変更 に進みましょう。