Документация South — Перевод. Часть 1: Основы

Добро пожаловать в руководство. Тут мы постараемся рассказать об основах использования South и дать несколько общих советов как ещё его можно использовать.
Если Вы никогда не слышали о библиотеках для миграции, тогда сперва прочитайте раздел «что такое миграция«. Это поможет Вам лучше понять для чего предназначены South и его альтернативы, такие как django-evolution.
В этом руководстве мы предполагаем, что South у Вас уже установлен и настроен, иначе смотрите раздел «установка«.

Приступаем

В этом руководстве мы рассмотрим процесс миграции на новое приложение. Вопросы изменения схемы существующего приложения мы рассмотрим позже.
Во-первых, надо отметить, что South работает с каждым приложением по отдельности. Миграции сохраняются в коде приложения (хотя их можно хранить там, где Вы захотите — см «SOUTH_MIGRATION_MODULES»). Если для приложения не определена никакая миграция, то South будет его просто игнорировать и оно будет использовать syncdb.
Так что возьмём проект для работы (или сделаем новое, определив БД и прочие настройки) и создадим новое приложение:
./manage.py startapp southtut
Как и предполагается, эта команда создаст новую папку southtut. Во-первых, добавьте это приложение в INTALLED_APPD, после чего откройте созданный 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

(Если на этом этапе Вы получите ошибку, что south_migrationhistory не существует, значит Вы забыли запустить syncdb после установки South)
Как Вы можете видеть, эта команда создала для нас папку миграции и создала внутри неё новую миграцию. Всё, что нам осталось — лишь применить её к БД:

 $ ./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.

Изменение модели

До сих пор мы не делали ничего, с чем бы не смог справиться 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 мы сможем сделать это всего в два шага: создать миграцию для отражения изменения и затем применить её:
Во-первых, создадим миграцию при помощи —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.

После этого наша новая колонка создана и опять же это можно проверить.

Конвертация существующего приложения

Иногда, особенно когда Вы добавляете South в проект, Вы хотите использовать его для уже существующего приложения — там, где уже есть созданные таблицы.
В этом и состоит отличие работы с существующим приложением от работы с новым приложением. И о том, как справиться с такой задачей смотрите страницу «конвертация приложения (пока не переведено)».
Теперь, когда Вы знаете как использовать South, можно перейти ко второй части руководства.

Автор: Ishayahu Lastov