.. _tutorial-part-1: Part 1: 基本 ============ .. Part 1: The Basics ================== .. Welcome to the South tutorial; here, we'll try and cover all the basic usage of South, as well as giving you some general hints about what else to do. South チュートリアルへようこそ; ここでは South の基本的な使用方法をカバーするだけでなく、また違う方法についての一般的なヒントも提供しています。 .. If you've never heard of the idea of a migrations library, then please read :ref:`what-are-migrations` first; that will help you get a better understanding of what both South (and others, such as django-evolution) are trying to achieve. もしマイグレーションライブラリの概念について聞いたこともない場合には :ref:`what-are-migrations` をまずお読み下さい; South (と django-evolution のような他のアプリ) が実現しようとしていることを理解する助けにもなるはずです。 .. This tutorial assumes you have South installed correctly; if not, see the :ref:`installation instructions `. このチュートリアルは South を既に正しくインストールしていることを前提としています; もしまだインストールしていなければ :ref:`インストールについての説明 ` をご覧下さい。 さあとりかかろう ---------------- .. Starting off ------------ .. In this tutorial, we'll follow the process of using migrations on a brand new app. Don't worry about converting your existing apps; we'll cover that in the next part. このチュートリアルでは、新規アプリケーションにマイグレーションを適用していく過程を追っていきます。 既存のアプリを変換したい場合も心配はいりません; ちゃんと次の章で説明します。 .. The first thing to note is that South is per-application; migrations are stored along with the app's code [#]_. If an app doesn't have any migrations defined, South will ignore it, and it will behave as normal (that is, using syncdb). 最初に注意すべきは、South は各アプリケーションを対象に動作するという点です; マイグレーションはアプリのコードと一緒に保存されます [#]_ 。 アプリにマイグレーションが定義されていない場合、South はそのアプリを無視して、標準の(つまり syncdb を使用した)処理を行います。 .. .. [#] You can also :ref:`store them elsewhere ` if you like. .. [#] お望みならば :ref:`マイグレーションを他の場所に保存する ` ことも可能です。 .. So, find a project to work in (or make a new one, and set it up with a database and other settings), and let's create our new app:: それでは South を組込むプロジェクトを見つけて(もしくは新規に作成して、データベースやその他の設定を行なって下さい) [*]_ 、 新しいアプリを作成しましょう:: ./manage.py startapp southtut .. [*] 訳注: ここで south_migrationhistory テーブルを作成するため、South 導入プロジェクトに対する syncdb が必要なはず .. As usual, this should make a new directory ``southtut/``. First, add it to ``INSTALLED_APPS``, then open up the newly-created ``southtut/models.py``, and create a new model:: ここで、いつものように新しく ``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() .. It's quite simple, but it'll do. Now, instead of running ``syncdb`` to create a table for the model in our database, we'll create a migration for it. シンプル過ぎますが、これだけで十分でしょう。 さて、データベースにモデルのテーブルを作るため ``syncdb`` を走らせるかわりに、 マイグレーションを作成しましょう。 最初のマイグレーション ---------------------- .. The First Migration ------------------- .. South has several ways of creating migrations; some are automatic, some are manual. As a basic user, you'll probably use the two automatic ways - ``--auto`` and ``--initial``. South にはマイグレーション生成の方法がいくつか; 自動的な方法も、手動で行う方法もあります。 基本的には、ふたつの自動的な方法 - ``--auto`` と ``--initial`` を使えばいいでしょう。 .. ``--auto`` looks at the previous migration, works out what's changed, and creates a migration which applies the differences - for example, if you add a field to a model, ``--auto`` will notice this, and make a migration which creates a new column for that field on its model's table. ``--auto`` は前回のマイグレーションを見て、何が変更されたのかを割り出し、 差分を適用するマイグレーションを生成します - 例えば、あるモデルにフィールドを追加した場合、 ``--auto`` はこの変更を検知して、追加フィールド用の新しいカラムを、 そのモデルのテーブルに追加するようなマイグレーションを生成します。 .. However, you'll notice that ``--auto`` needs a previous migration - our new app doesn't have one. Instead, in this case, we need to use ``--initial``, which will create tables and indexes for all of the models in the app; it's what you use first, much like ``syncdb``, and ``--auto`` is then used afterwards for each change. ``--auto`` には前回のマイグレーションが必要、ということがわかったと思いますが、 新規作成したアプリにはまだマイグレーションがありません。 その代わり、この場合には、アプリ内の全モデルのテーブルとインデックスを生成する ``--initial`` を使う必要があります; ``syncdb`` と同じように、まず最初にこれを使えば、それ以降の ``--auto`` はその前のマイグレーションを使用します。 .. So, let's create our first migration:: では、最初のマイグレーションを作りましょう:: $ ./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 .. As you can see, that's created a migrations directory for us, and made a new migration inside it. All we need to do now is apply our new migration:: ご覧のように、migrations ディレクトリが作られて、その下に新しいマイグレーションが生成されました。 次に、この新しくできたマイグレーションを適用しましょう:: $ ./manage.py migrate southtut Running migrations for southtut: - Migrating forwards to 0001_initial. > southtut:0001_initial - Loading initial data for southtut. .. With that, South has created the new table for our model; check if you like, and try adding a few Knights using ``./manage.py shell``. これで South は Knight モデル用の新しいテーブルを作成しました; よければ ``./manage.py shell`` を使って確認したり、いくつか Knight を追加してみて下さい。 .. Changing the model ------------------ モデルの変更 ------------ .. So far, we've done nothing that ``syncdb`` couldn't accomplish; time to change that (or rather, our model). Let's add another field to our model:: 今までのところ ``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() .. Now, if we weren't using migrations, making this new column appear on our ``southtut_knight`` table would be annoying at best. However, with South, we need only do two, quick steps: make a migration for the change, then apply it. さて、マイグレーションが無ければ、 ``southtut_knight`` テーブルに新しいカラムを追加するのは、 どれだけ贔屓目に見ても、面倒な作業でしかありません。しかし South を使っていれば、やることは たった 2 ステップだけです; 今回の変更に対するマイグレーションの作成と、その適用です。 .. First, make the new migration, using the --auto feature:: まず ``--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 .. *(Notice that South has automatically picked a name for this migration; you can instead give migrations custom names by providing it as another argument)* *(South は自動的にマイグレーション名を選定する点に注意して下さい; 引数に渡すことで、カスタムマイグレーション名を指定することもできます)* .. Now, apply it:: 次に、これを適用しましょう:: $ ./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. .. With that, our new column is created; again, go and check, you'll be able to add Knights who can dance whenever they're able. これで新しいカラムが作成されました; 再度確認してみましょう。 dances_whenever_able フィールドを持つ Knight を追加することができると思います。 .. Once you're happy with this basic usage of South, move on to :ref:`tutorial-part-2`. ここまでで South の基本的な使用法がわかったので :ref:`tutorial-part-2` に進みましょう。