Команды¶

Django предоставляет две команды для работы с миграциями и структурой базы данных:

• migrate, которая отвечает за применение миграций, за откат миграций и за вывод статуса миграций.

• makemigrations, которая отвечает за создание новых миграций на основе изменений в моделях.

• sqlmigrate, которая выводит SQL запросы для миграции.

• sqlmigrate, которая выводит SQL запросы для миграции.

Следует рассматривать миграции, как систему контроля версий для базы данных. makemigrations отвечает за сохранение состояния моделей в файле миграции - аналог коммита - а migrate отвечает за их применение к базе данных.

Файлы с миграциями находятся в каталоге «migrations» приложения. Они являются частью приложения и должны распространятся вместе с остальным кодом приложения. Они должны создаваться при разработке и потом применятся на машинах коллег, тестовом и «боевом» серверах.

Миграции работают идентично на одном и том же наборе данных. Это означает, что на сервере разработки, тестовом и «боевом» серверах вы получите один и тот же результат при одинаковых условиях выполнения миграций.

Django создаст миграции при любых изменениях модели или полей - даже тех параметров, которые не влияют на базу данных - т.к. единственный способ восстановить состояние моделей - это хранить все изменения в истории. Вам могут понадобится эти параметры в миграциях данных в будущем (например, если вы добавите собственную проверку данных).

Поддержка бэкендами¶

Миграции поддерживаются всеми бэкендами, которые предоставляет Django, как и сторонними, если они реализуют API внесения изменений в структуру базы данных (через класс SchemaEditor).

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

Работа с миграциями¶

Django может создавать миграции за вас. Внесите изменения в свои модели — скажем, добавьте поле и удалите модель — а затем запустите makemigrations:

$ python manage.py makemigrations
Migrations for 'books':
  books/migrations/0003_auto.py:
    ~ Alter field author on book

Ваши модели будут просканированы и сравнены с версией, которая содержится в файлах миграций, затем будут созданы новые миграции. Не забывайте проверять вывод команды, чтобы понимать, как makemigrations видит ваши изменения - для сложных изменений вы можете получить не совсем ожидаемый результат.

Получив новые файлы миграции, вам следует применить их к своей базе данных, чтобы убедиться, что они работают должным образом:

$ python manage.py migrate
Operations to perform:
  Apply all migrations: books
Running migrations:
  Applying books.0003_auto... OK

После того, как миграция отработала, добавьте миграции и изменения к моделям в одном коммите - таким образом, когда другие разработчики (или на «боевом» сервере) обновят код, они получат как изменения ваших моделей, так и миграции для них.

Если вы хотите дать миграции значимое имя вместо сгенерированного, вы можете использовать опцию makemigrations --name:

$ python manage.py makemigrations --name changed_my_model your_app_label

Транзакции¶

В базах данных, поддерживающих транзакции DDL (SQLite и PostgreSQL), все операции миграции по умолчанию выполняются внутри одной транзакции. Напротив, если база данных не поддерживает транзакции DDL (например, MySQL, Oracle), то все операции будут выполняться без транзакции.

Вы можете предотвратить запуск миграции в транзакции, установив для атрибута atomic значение False. Например:

from django.db import migrations


class Migration(migrations.Migration):
    atomic = False

Также возможно выполнить части миграции внутри транзакции, используя atomic() или передав atomic=True в RunPython. Подробнее см. Неатомарные миграции.

Зависимости¶

В то время как миграция находятся в контексте одного приложения, таблицы и зависимости, определенные вашими моделями, обычно намного сложнее, и могут работать не только с одним приложением. Когда вы делаете миграцию, которая требует что-то ещё для запуска - например, вы добавляете ForeignKey в вашем books приложении на приложение authors - в результате миграция будет содержать зависимость от миграции в authors.

Это означает, что при запуске миграции сначала запускается миграция authors и создается таблица, на которую ссылается ForeignKey, а затем миграция, которая создает столбец ForeignKey, запускается позже и создает ограничение. Если этого не произойдет, миграция попытается создать столбец «ForeignKey» без существующей таблицы, на которую он ссылается, и ваша база данных выдаст ошибку.

Такое поведение зависимостей влияет на большинство миграционных операций, которые вы ограничили рамками одного приложения. Подобное ограничение (в makemigrations или migrate) было отличным обещанием, но не гарантией. Любое другое приложение, которое потребуется для удовлетворения зависимости, будет использовано автоматически.

Приложения без миграции не должны иметь связей («ForeignKey», «ManyToManyField» и т. д.) с приложениями с миграцией. Иногда это может работать, но не поддерживается.

Файлы с миграциями¶

Миграции сохраняются в так называемых «файлах миграции». Это обычные Python файлы с классом миграции, который соблюдает определенный интерфейс. В нём декларативно можно описать все необходимые операции и прочее.

Базовый файл миграции выглядит следующим образом:

from django.db import migrations, models


class Migration(migrations.Migration):
    dependencies = [("migrations", "0001_initial")]

    operations = [
        migrations.DeleteModel("Tribble"),
        migrations.AddField("Author", "rating", models.IntegerField(default=0)),
    ]

При загрузке файла миграции (импортируя как Python модуль) Django ищет дочерний класс django.db.migrations.Migration, который должен называться Migration. Затем он анализирует четыре атрибута класса, из которых обычно используются только два:

• dependencies - список зависимых миграций.

• operations - список подклассов Operation, которые определяют необходимые для миграции операции.

Список операций - самое главное в миграции. Он декларативно описывает необходимые операции для изменения структуры базы данных. Django анализирует все операции и в памяти строит схему всех необходимых изменений, чтобы сгенерировать необходимые SQL-запросы.

Схема в памяти также используется чтобы определить отличия между вашими текущими моделями и состоянием моделей, описанном в миграциях. Django проходит по всем изменениям и создает структуру моделей на момент последнего выполнения makemigrations. Затем эта структура сравнивается со структурой моделей в models.py и определяются изменения, которые вы внесли в ваши модели.

Скорее всего вам никогда не понадобится менять сгенерированные миграции, но при необходимости вы можете сами написать миграцию. Некоторые сложные изменения Django не может автоматически определить, в таких случаях их необходимо описать самостоятельно. Но не бойтесь, это несложно.

class MyManager(models.Manager):
    use_in_migrations = True


class MyModel(models.Model):
    objects = MyManager()

class MyManager(MyBaseManager.from_queryset(CustomQuerySet)):
    use_in_migrations = True


class MyModel(models.Model):
    objects = MyManager()

Добавление миграций в приложение¶

Добавить миграции в новое приложение очень просто. Они уже настроены на использование миграций. Просто выполните makemigrations после изменений моделей.

Если в вашем приложении уже есть модели и таблицы базы данных и еще нет миграций (например, вы создали его на основе предыдущей версии Django), вам необходимо преобразовать его для использования миграций, выполнив:

$ python manage.py makemigrations your_app_label

В приложении будет создана начальная миграция. Теперь выполните python manage.py migrate --fake-initial, Django увидит начальную миграцию, и что таблицы, которые необходимо создать, уже существуют, и просто пометит миграцию как уже выполненную. (Без флага :djadminopt:`--fake-initial` команда migrate вернет ошибку т.к. таблицы, которые она пытается создать, уже существуют.)

Обратите внимание, это работает только при соблюдении следующих условий:

• Вы не меняли модели после создания таблиц в базе данных. Чтобы миграции сработали, необходимо сначала создать начальную миграцию, а потом вносить изменения, т.к. Django определяет изменения по файлам миграций, а не структуре в базе данных.

• Вы не меняли самостоятельно структуру базы данных. Django не сможет определить, что структура базы данных не соответствует структуре ваших моделей. Скорее всего вы получите ошибку при выполнении миграций.

Реверсивные миграции¶

Миграцию можно отменить с помощью migrate, передав номер предыдущей миграции. Например, чтобы отменить миграцию books.0003:

$ python manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto... OK

...\> py manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto... OK

Если вы хотите отменить все миграции, примененные к приложению, используйте имя «ноль»:

$ python manage.py migrate books zero
Operations to perform:
  Unapply all migrations: books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0002_auto... OK
  Unapplying books.0001_initial... OK

...\> py manage.py migrate books zero
Operations to perform:
  Unapply all migrations: books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0002_auto... OK
  Unapplying books.0001_initial... OK

Миграция является необратимой, если она содержит какие-либо необратимые операции. Попытка отменить такую ​​миграцию вызовет ошибку «IrreversibleError»:

$ python manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto...Traceback (most recent call last):
django.db.migrations.exceptions.IrreversibleError: Operation <RunSQL  sql='DROP TABLE demo_books'> in books.0003_auto is not reversible

...\> py manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto...Traceback (most recent call last):
django.db.migrations.exceptions.IrreversibleError: Operation <RunSQL  sql='DROP TABLE demo_books'> in books.0003_auto is not reversible

«Исторические» модели¶

При выполнении миграций Django использует сгенерированные версии ваших моделей, которые хранятся в файлах миграций. Если вы пишете Python код для выполнения миграции, используя операцию RunPython, или добавляете метод allow_migrate в ваш роутер базы данных, Django предоставит вам эти модели для использования.

Т.к. невозможно сериализовать произвольный код Python, эти версии моделей не будут содержать методы, который вы добавили в модели. Однако, модели будут содержать аналогичные поля, связи, менеджеры(только те, которые содержат use_in_migrations = True) и параметры Meta (с учетом версии модели, так что они могут отличаться от моделей, которые находятся на данный момент в приложении).

Ссылки на функции, которые используются в параметрах поля (например, upload_to и limit_choices_to), и менеджеры моделей с use_in_migrations = True будут сериализированы в миграциях. Такие функции нельзя удалять из кода проекта, пока существуют миграции, которые ссылаются на них. Все собственные поля моделей также должы быть доступны т.к. они явно импортируются в миграциях.

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

Чтобы удалить старые ссылки, вы можете сжать миграции или, если ссылок не так много, скопировать их в файлы миграции.

Советы по удалению полей модели¶

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

Чтобы помочь решить эту проблему, были добавлены атрибуты в поля модели, которые могут указать на устаревшие поля при проверке проекта.

Добавьте атрибут system_check_deprecated_details к полю модели:

class IPAddressField(Field):
    system_check_deprecated_details = {
        "msg": (
            "IPAddressField has been deprecated. Support for it (except "
            "in historical migrations) will be removed in Django 1.9."
        ),
        "hint": "Use GenericIPAddressField instead.",  # optional
        "id": "fields.W900",  # pick a unique ID for your field.
    }

После определенного периода поддержки устаревшего кода (Django использует три мажорных релиза для своих полей), замените system_check_deprecated_details на system_check_removed_details со следующим значением:

class IPAddressField(Field):
    system_check_removed_details = {
        "msg": (
            "IPAddressField has been removed except for support in "
            "historical migrations."
        ),
        "hint": "Use GenericIPAddressField instead.",
        "id": "fields.E900",  # pick a unique ID for your field.
    }

Вы должны сохранить методы поля поля, которые используются в миграции: __init__(), deconstruct() и get_internal_type(). Храните это поле-заглушку, пока существуют миграции, которые ссылаются на него. Например, после объединения миграций и удаления старых, вы сможете полностью удалить эти поля.

Миграция данных¶

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

Миграции, которые изменяют данные, обычно называют «миграциями данных». Их лучше выносить в отдельную миграцию.

Django не может автоматически создать миграции данных для вас, как это происходит с миграциями структуры, но их не сложно создать самостоятельно. Файлы миграций в Django содержат Операции. Для миграций данных вы будете использовать в основном RunPython.

Для начала создайте пустой файл миграции, с которым вы сможете работать (Django поместит файл в нужное место, предложит имя и добавит зависимости):

python manage.py makemigrations --empty yourappname

Теперь откройте файл, он будет выглядеть следующим образом:

# Generated by Django A.B on YYYY-MM-DD HH:MM
from django.db import migrations


class Migration(migrations.Migration):
    dependencies = [
        ("yourappname", "0001_initial"),
    ]

    operations = []

Теперь все, что вам нужно сделать, это создать новую функцию и позволить RunPython использовать ее. RunPython ожидает вызываемый объект в качестве аргумента, который принимает два аргумента: первый — это реестр приложений, в который загружены исторические версии всех ваших моделей, соответствующие тому, где в вашей истории находится миграция, а второй — это SchemaEditor, который вы можете используйте для внесения изменений в схему базы данных вручную (но будьте осторожны, это может сбить с толку автодетектор миграции).

Давайте создадим простую миграцию, которая заполняет новое поле name комбинацией значений first_name и last_name. Для этого будем использовать текущую версию модели и в цикле изменим все объекты:

from django.db import migrations


def combine_names(apps, schema_editor):
    # We can't import the Person model directly as it may be a newer
    # version than this migration expects. We use the historical version.
    Person = apps.get_model("yourappname", "Person")
    for person in Person.objects.all():
        person.name = f"{person.first_name} {person.last_name}"
        person.save()


class Migration(migrations.Migration):
    dependencies = [
        ("yourappname", "0001_initial"),
    ]

    operations = [
        migrations.RunPython(combine_names),
    ]

Теперь выполним python manage.py migrate и миграция данных будет применена вместе с остальными миграциями.

Вы можете передать вторым аргументом RunPython еще одну функцию, которая будет использоваться при отмене миграции. Если такая функция не указана, то при попытке отменить миграцию будет вызвано исключение.

class Migration(migrations.Migration):
    dependencies = [
        ("app1", "0001_initial"),
        # added dependency to enable using models from app2 in move_m1
        ("app2", "0004_foobar"),
    ]

    operations = [
        migrations.RunPython(move_m1),
    ]

Объединение миграций¶

Вы можете создавать сколько угодно миграций и не задумываться об их количестве. Код миграций оптимизирован и может работать с сотнями миграций за вменяемое время. Но, если вы хотите уменьшить количество миграций, вы можете объединить их.

Объединение позволяет сократить количество миграций до одной (или нескольких), которая будет выполнять аналогичные изменения структуры.

Django загрузит все ваши миграции, соберёт последовательность объектов Operation, затем попытается оптимизировать и сократить этот список. Например, Django понимает, что CreateModel и DeleteModel отменяют друг друга, и что AddField может быть добавлена в CreateModel.

Когда список операций будет оптимизирован насколько возможно - это зависит от сложности связей между моделями, использовались ли операции RunSQL или RunPython (которые нельзя оптимизировать) - Django добавит их в новые миграции.

Эти файлы помечены так, что они заменяют ранее сжатые миграции, поэтому они могут сосуществовать со старыми файлами миграции, и Django будет разумно переключаться между ними в зависимости от того, где вы находитесь в истории. Если вы все еще находитесь на полпути к набору миграций, которые вы удалили, он будет продолжать использовать их до тех пор, пока не дойдет до конца, а затем переключится на сжатую историю, в то время как новые установки будут использовать новую сжатую миграцию и пропускать все старые.

Это позволяет объединить миграции и не сломать проект на сервере, который ещё не обновили до последней версии. Рекомендуем следующую последовательность действий: объединяем миграции, старые не удаляем, коммитим и обновляем все сервера при следующем релизе (если это распространяемое приложение, убеждаемся, что все пользователи обновились до последней версии), удаляем старые миграции, коммитим и обновляем сервера до последней релизной версии.

Команда, которая поддерживает все это, — squashmigrations - передайте ей метку приложения и имя миграции, до которой вы хотите сжать, и она начнет работать:

$ ./manage.py squashmigrations myapp 0004
Will squash the following migrations:
 - 0001_initial
 - 0002_some_change
 - 0003_another_change
 - 0004_undo_something
Do you wish to proceed? [y/N] y
Optimizing...
  Optimized from 12 operations to 7 operations.
Created new squashed migration /home/andrew/Programs/DjangoTest/test/migrations/0001_squashed_0004_undo_something.py
  You should commit this migration but leave the old ones in place;
  the new migration will be used for new installs. Once you are sure
  all instances of the codebase have applied the migrations you squashed,
  you can delete them.

Используйте опцию squashmigrations --squashed-name, если вы хотите установить имя сжатой миграции, а не использовать автоматически сгенерированное.

Обратите внимание, зависимости между моделями могут быть очень сложными. В результате объединения может получиться неработающая миграция или неправильно оптимизированная (в этом случае можете попробовать с опцией --no-optimize, и желательно сообщить нам о проблеме), или может вызывать исключение CircularDependencyError (в этом случае вы можете самостоятельно исправить проблему).

Чтобы устранить исключение CircularDependencyError, вынесите один из ForeignKey, который привел к циклической зависимости, в отдельную миграцию и перенести зависимость миграции в другое приложение, которое использует этот ForeignKey. Если вы не уверены как сделать это правильно, посмотрите как makemigrations делает это при создании новой миграции по вашим моделям. В следующих версиях Django мы обновим squashmigrations, чтобы такие проблемы решались автоматически.

После объединения миграций закоммитьте их, не удаляя старые миграции. После этого обновите все установленные версии проекта.

Затем вы можете преобразовать сжатую миграцию в обычную миграцию:

• Удалите все миграции, которые она заменяет

• Обновление всех миграций, которые зависят от удаленных миграций, чтобы они зависели от сжатой миграции.

• Удалите аргумент replaces в классе Migration объединенной миграции (он указывает Django, что это объединенная миграция)

Сериализация значений¶

Миграции - это Python файлы, которые содержат старые определения ваших моделей. Поэтому, чтобы создать их, Django необходимо получить текущее состояние ваших моделей и сериализовать его в файле.

Хотя Django может сериализовать большинство вещей, есть некоторые веши, которые нельзя сериализовать в представление Python - нет в Python стандарта, который определяет как преобразовать значение обратно в код (repr() работает только для простых значений и не позволяет указать путь для импорта).

Django позволяет сериализовать следующее:

• int, long, float, bool, str, unicode, bytes, None

• список, набор, кортеж, дикт, диапазон

• Объекты datetime.date, datetime.time и datetime.datetime (включая те, у которых указан часовой пояс)

• Экземпляры zoneinfo.ZoneInfo

• Объекты decimal.Decimal

• Экземпляры enum.Enum и enum.Flag

• Объекты decimal.Decimal

• Экземпляры functools.partial() и functools.partialmethod, которые имеют сериализуемые значения func, args и keywords.

• Чистые и конкретные объекты пути из pathlib. Конкретные пути преобразуются в их чистый эквивалент пути, например. от pathlib.PosixPath до pathlib.PurePosixPath

• Экземпляры os.PathLike, например. os.DirEntry, которые преобразуются в str или bytes с помощью os.fspath()

• Экземпляры LazyObject, которые оборачивают сериализуемое значение.

• Экземпляры типов перечисления (например, TextChoices или IntegerChoices).

• Любое поле Django

• Ссылку на любую функцию или метод (например datetime.datetime.today) (должны быть доступны на уровне модуля)

  • Функции могут быть декорированы, если они правильно обернуты, например, с использованием functools.wraps()

  • Декораторы functools.cache() и functools.lru_cache() явно поддерживаются.

• Непривязанные методы в теле класса (смотрите ниже)

• Ссылка на класс (должны быть доступны на уровне модуля)

• Любой объект с методом deconstruct() (смотрите ниже)

Django не может сериализовать:

• Вложенные классы

• Экземпляры произвольного класса (например MyClass(4.3, 5.7))

• Лямбда-функции

from decimal import Decimal

from django.db.migrations.serializer import BaseSerializer
from django.db.migrations.writer import MigrationWriter


class DecimalSerializer(BaseSerializer):
    def serialize(self):
        return repr(self.value), {"from decimal import Decimal"}


MigrationWriter.register_serializer(Decimal, DecimalSerializer)

from django.utils.deconstruct import deconstructible


@deconstructible
class MyCustomClass:
    def __init__(self, foo=1):
        self.foo = foo
        ...

    def __eq__(self, other):
        return self.foo == other.foo

Поддержка нескольких версий Django¶

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

Система миграций поддерживает обратную совместимость как и остальная часть Django, и файлы миграций для Django X.Y должны работать для Django X.Y+1. Однако, система миграций не гарантирует обратную совместимость. Могут добавляться новые возможности и новые миграции не будут работать на старой версии Django.