Архив рубрики: Django

Документация South — Перевод. Часть 2. Более сложные изменения схемы

Теперь, когда мы знаем как обслуживать простые изменения модели, давайте посмотрим на более сложные случаи, которые Вы так же можете обработать при помощи South.

Значение по умолчанию

Во-первых, давайте займёмся более хитрыми типами колонок. В прошлой части мы добавили BooleanField в таблицу — такую операцию БД легко обработать, так как у него есть значение по умолчанию (False). Это значение и будет установлено для всех уже имеющихся записей в БД.
Однако для некоторых колонок нет предопределённого значения по умолчанию. Если в колонке может присутствовать значение null, то есть null = True, тогда уже существующие записи получат значение null. В противном же случае, если колонка NOT NULL (null = False, свойство колонки по умолчанию), то в таком случае нет значения, которое БД могла бы присвоить уже имеющимся записям, так что Вы не сможете просто добавить колонку (однако, некоторые БД могут позволить Вам добавить колонку в пустую таблицу).
Если South обнаружит такую ситуацию, он тут же спросит у Вас что делать. Давайте посмотрим на это.
Для начала изменим нашу модель добавив поле, которое не имеет значения по умолчанию и не может быть равно null:
 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()
     shrubberies = models.IntegerField(null=False)
Теперь давайте попробуем сделать миграцию на эту модель:
 ./manage.py schemamigration southtut --auto
  ? The field 'Knight.shrubberies' does not have a default specified, yet is NOT NULL.
  ? Since you are adding or removing this field, you MUST specify a default
  ? value to use for existing rows. Would you like to:
  ?  1. Quit now, and add a default to the field in models.py
  ?  2. Specify a one-off value to use for existing columns now
  ? Please select a choice:
South предлагает Вам два варианта: если вы выбираете вариант 1, не будет сделано ничего и Вам надо будет отредактировать models.py  и добавить значение по умолчанию для поля.
Если же Вы выбираете вариант 2, то Вы должны будете ввести в приглашение интерпретатора Python значение по умолчанию для этой миграции. Это значение будет использоваться только для тех записей, которые присутствуют в таблице на данный момент, так что это хороший вариант, если Вы не хотите, чтобы это поле имело значение по умолчанию.
Мы выберем вариант 2 и в качестве значения по умолчанию используем 0 (так как это, в конце концов, числовое поле):
  ? Please select a choice: 2
  ? Please enter Python code for your one-off default value.
  ? The datetime module is available, so you can do e.g. datetime.date.today()
  >>> 0
  + Added field shrubberies on southtut.Knight
 Created 0003_auto__add_field_knight_shrubberies.py. You can now apply this migration with: ./manage.py migrate southtut
Если Вы посмотрите на сгенерированную миграцию, то Вы увидите, что для нового поля установлено значение по умолчанию, так что жаловаться БД не будет. Завершим нашу миграцию:
$ ./manage.py migrate southtut
 Running migrations for southtut:
  - Migrating forwards to 0003_auto__add_field_knight_shrubberies.
  > southtut:0003_auto__add_field_knight_shrubberies
  - Loading initial data for southtut.

Уникальные значения

Кроме обнаружения новых полей (или удаления старых) South так же может обнаружить большее количество изменений в самих полях, в том числе изменение их атрибута unique.
Во-первых, давайте изменим схему нашего Knigts, чтобы он имел уникальные поля:
 from django.db import models

 class Knight(models.Model):
     name = models.CharField(max_length=100, unique=True)
     of_the_round_table = models.BooleanField()
     dances_whenever_able = models.BooleanField()
     shrubberies = models.IntegerField(null=False)
Теперь запустим создание автоматической миграции:
 $ ./manage.py schemamigration --auto southtut
  + Added unique constraint for ['name'] on southtut.Knight
 Created 0004_auto__add_unique_knight_name.py. You can now apply this migration with: ./manage.py migrate southtut
Как Вы можете видеть, он определил появление нового ограничения на поле name. Вы можете теперь применить его:
 $ ./manage.py migrate southtut
 Running migrations for southtut:
  - Migrating forwards to 0004_auto__add_unique_knight_name.
  > southtut:0004_auto__add_unique_knight_name
  - Loading initial data for southtut.
Кроме того, South может обнаружить появление или изменение unique_together в подклассе Meta вашей модели.

Поля ManyToMany

South должен автоматически определять поля ManyToMany. Когда Вы добавляете такое поле, South создаёт таблицу, представляющую это отношение, а когда удаляете — South её удаляет.
Единственное исключение — through model, т. е. если Вы используете опцию through. Так как таблица для этой модели уже создана, South не будет делать ничего с этими полями ManyToMany.

Пользовательские поля

Если Вы внимательнее посмотрите на файлы миграции, Вы увидите, что South хранит определения полей сохраняя их класс и аргументы, необходимые для передачи в конструктор поля.
Так как в Python нет способа получить аргументы, используемые в классе конструктора, напрямую, South использует нечто под названием «model introspector» для того, чтобы выяснить, какие аргументы были переданы в конструктор поля. Мы узнаем, что хранится в переменных, которым присваивается значение аргументов и таким образом можем реконструировать сами переданные значения.
Поскольку пользовательские поля (написанные Вами или полученные от сторонних приложений) совсем другие, South не может получить значения для их аргументов без дополнительной помощи. Так что если Вы хотите добавить / изменить / удалить пользовательское поле, South понадобится ваша помощь и он попросит Вас задать правила для этих полей. Эта тема будет затронута в разделе «пользовательские поля».

Ещё?

South поддерживает большинство операций, с которыми Вы будете встречаться каждый день. Если Вам интересно — то есть полный список автоопределяемых изменений.
Теперь, скорее всего, Вам захочется прочитать третью часть руководства.

Автор: Ishayahu Lastov

Документация South — Перевод. Установка

Текущий релиз South — 0.7.6. Но документация написана для 0.7.5, так что имейте это ввиду.
Есть несколько способов установить South:

  • Используя easy_install или pip, что рекомендуется, если Вы хотите получить стабильный релиз
  • Используя Mercurial, что рекомендуется если Вы хотите получить самый последний релиз
  • Скачав архив, если у Вас нет ни easy_install, ни Mercurial
Некоторые дистрибутивы Linux (и UNIX, например, FreeBSD — прим. переводчика) уже содержат South в их репозитории, например, если Вы используете не стабильный Debian, то Вы можете использовать команду apt-get install python-django-south, а на Fedora — yum install Django-south. Обратите внимание, что таким образом Вы можете получить старую версию, так что проверьте сначала номер версии в репозитории.
South <=0.7.3 должен работать с версиями Django от 0.97-pre до 1.1
South >=0.7.4 должен работать с версиями Django начиная от версии 1.2
Пожалуйста, проверьте совместимость с вашей версией в заметках о релизе, чтобы быть в курсе последних изменений.

Установка при помощи easy_install

Если у Вас есть easy_install, то просто выполните команду easy_install South. Если у Вас уже установлена предыдущая версия и Вы просто хотите её обновить — используйте команду easy_install -U South. Вот и всё, что Вам нужно для установки пакета. Теперь Вам следует настроить Django (см. последний раздел).

Установка при помощи Mercurial

Вы можете так же воспользоваться возможностью установки напрямую из нашего репозитория Mercurial, что позволит Вам получить все обновления и исправления ошибок сразу по их выходу. Для этого Вам нужен установленный Mercurial. На большинстве систем соответствующий пакет называется mercurial; для Windows и OSX пакет можно скачать с http://mercurial.berkwood.com.
Убедитесь, что Вы находитесь в той папке, куда и хотите получить south. После этого выполните команду hg clone http://bitbucket.org/andrewgodwin/south/ Для обновления имеющейся версии выполните две команды:
hg pull
hg up -C tip
(Вместо использования tip Вы так же можете использовать тег stableish, который в ручную устанавливается на стабильные коммиты, или же выбрать тег с номером версии)
После этого переходите к разделу «установка из папки»

Использование скачиваемого архива

Если Вы питаете отвращение к использованию Mercurial и не имеете под рукой easy_install, тогда Вы можете установить South из нашего .tar.gz файла.
Во-первых, скачайте архив со страницы релизов и извлеките его в папку south. После этого следуйте инструкциям из раздела «установка из папки».

Установка из папки

Если Вы получили копию South при помощи Mercurial или скачав и распаковав архив, то теперь Вам надо установить South на вашу систему. Попробуйте выполнить эту команду:
python setup.py develop
Если она не сработает, значит на вашей системе не доступны setuptools. Тогда либо установите их, либо выполните команду
python setup.py install
Обратите внимание, что при использовании develop Вы будете запускать установленную версию из той папки, которую Вы создали, тогда как при использовании install Вы скопируете все файлы в папку site-packages вашей версии Python, а значит при обновлении Вам снова понадобится использовать команду install.
Вы так же можете установить South локально, только для одного проекта, либо включив его в этот проект и изменив sys.path в файле настрое, либо (предпочтительнее) используя virtualenv, pip и requirements.txt. Рассказ о том, как это сделать выходит за рамки этой документации, то его не тяжело найти в сети.
После установки Вам надо будет настроить вашу версию Django.

Настройка Django

После того, как Вы установили South на вашей системе, Вам осталось только настроить Django, чтобы он его использовал. Сделать это просто — достаточно отредактировать setti
ngs.py, добавив 'south' в конец раздела INSATALLED_APPS.
Если Django не торопится подхватывать South, то проверьте что Вы нигде не переопределили INSTALLED_APS, и что Вы можете выполнить import south в ./manage.py shell без ошибок.
После того, как South добавлен, Вам надо запустить ./manage.py syncdb чтобы South создал таблицу для слежения за изменениями (South не использует миграции для своих моделей по некоторым причинам).
Теперь South загружен в ваш проект и готов к использованию. Так что перейдём к более интересным занятиям.

Автор: Ishayahu Lastov

Документация 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

Документация South — Перевод. Что такое миграция?

Для непосвящённых: миграция (migrations), так же известная как 'schema evolution' или 'mutations' — это способ изменения схемы вашей БД с одной версии на другую. Django сам по себе может лишь добавлять новые модели, но почти во всех проектах часто происходят изменения самой модели — добавляются поля, изменятся свойства полей, и т.д.
South, и другие аналогичные решения, предоставляет способ обойти эту проблему, давая Вам инструмент для лёгкого и предсказуемого изменения схемы вашей БД. Вы пишете миграцию, которая говорит South как перейти с одной версии на другую, и, связывая эти миграции в цепочку, Вы можете двигаться вперёд или назад по истории изменений схемы вашей БД. 
В South, миграция это так же способ создания БД — первая миграция на самом деле миграция из пустой схемы к вашей схеме. Таким образом Вы можете как воссоздать самую последнюю версию схемы БД, так и проапгрейдить любую из устаревших, просто запустив миграцию с определённой точки. 
В процессе этого руководства мы покажем Вам как миграция работает и как она может быть полезна на разных примерах.

Автор: Ishayahu Lastov

Документация South — Перевод. Про South

South привносит миграцию в приложения на Django. Его главная цель — предоставить простой, стабильный и независящий от БД слой миграции чтобы избавить Вас от хлопот по обслуживанию изменений схемы БД в ваших приложениях.

Мы стараемся сделать South как простым в использовании, так и интуитивно понятным, насколько это возможно. Для этого мы автоматизируем большую часть задач по изменению схемы в то же время предоставляя мощный набор инструментов для сложных проектов. Вы можете легко написать вашу собственную миграцию руками или использовать API для изменения БД.

Хотя South начинался как малоизвестный проект, он медленно набирал популярность и теперь стал одним из самых популярных инструментов для изменения схемы приложений Django.

Основные возможности

  • Создание автоматической миграции: South может отслеживать изменения в файле models.py file и автоматически создавать миграцию, которая отражает эти изменения.
  • Не зависит от конкретной БД: Насколько это вообще возможно South не зависит от используемой Вами БД, поддерживая 5 типов БД.
  • Подкован в приложениях: South знает что такое приложения и умеет с ними работать, позволяя Вам проводить миграцию для некоторых ваших приложений и оставляя остальные на совести syncdb.
  • VCS-proof: South оповестит Вас если кто-то ещё делает миграцию для выбранного приложения и ваши миграции вступают в конфликт.

Краткая история

Изначально South был разработан Torchbox в 2008, когда ещё не было другой системы, которая могла предоставить нам необходимый функционал. В короткие сроки код системы был открыт и она получила популярность после представления на панели Schema Evolution на DjangoCon 2008.

Где-то в 2009, она стала самой популярной системой среди всех альтернативных вариантов и, похоже, её популярность будет только расти. Хотя есть множество запросов по интеграции South или чего-то похожего напрямую в Django, такой интеграции ещё не было сделано, в основном по причине некоторой незрелости систем миграции.

Автор: Ishayahu Lastov