Миграции

Команды

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

• migrate, которая отвечает за применение и отмену миграций.
• makemigrations, которая отвечает за создание новых миграций на основе изменений, внесённых в модели.
• sqlmigrate, которая отображает SQL-операторы для миграции.
• showmigrations, которая выводит список миграций проекта и их состояние.

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

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

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

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

Поддержка серверных СУБД

Миграции поддерживаются всеми серверными СУБД, входящими в поставку Django, а также сторонними СУБД, если в них реализована поддержка изменения схемы (через класс 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:
  Rendering model states... DONE
  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. Затем Django проверяет у этого объекта четыре атрибута, из которых обычно используются только два:

• dependencies — список миграций, от которых зависит эта миграция.
• operations — список классов Operation, описывающих действия этой миграции.

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

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

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

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 обнаружит, что у вас есть начальная миграция и что таблицы, которые он хочет создать, уже существуют, и пометит миграцию как уже применённую. (Без флага migrate --fake-initial команда завершится ошибкой, поскольку таблицы, которые она хочет создать, уже существуют.)

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

• С момента создания таблиц модели не менялись. Чтобы миграции работали, сначала необходимо создать начальную миграцию, а уже затем вносить изменения, поскольку 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

Чтобы отменить все применённые миграции приложения, укажите имя zero:

$ 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 в маршрутизаторах баз данных, необходимо использовать эти исторические версии моделей, а не импортировать модели напрямую.

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

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

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

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

Что учитывать при удалении полей модели

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

Для решения этой проблемы Django предоставляет атрибуты полей модели, помогающие выполнять их устаревание с помощью инфраструктуры системных проверок.

Добавьте к полю модели атрибут 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 (которые нельзя оптимизировать, если они не помечены как elidable), — Django запишет результат в новый набор файлов миграций.

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

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

Для всего этого используется команда 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, если хотите задать имя объединённой миграции, а не использовать автоматически сгенерированное.

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

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

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

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

• Удалите все заменённые ею файлы миграций.
• Обновите все миграции, зависящие от удалённых миграций, чтобы вместо них они зависели от объединённой миграции.
• Удалите атрибут replaces из класса Migration объединённой миграции (по нему Django определяет, что миграция объединённая).

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

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

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

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

• int, float, bool, str, bytes, None, NoneType
• list, set, tuple, dict, range
• экземпляры datetime.date, datetime.time и datetime.datetime (в том числе с учётом часового пояса)
• экземпляры zoneinfo.ZoneInfo
• экземпляры decimal.Decimal
• экземпляры enum.Enum и enum.Flag
• экземпляры uuid.UUID
• экземпляры functools.partial() и functools.partialmethod, у которых значения func, args и keywords можно сериализовать
• Объекты путей pure и concrete из pathlib. Пути concrete преобразуются в соответствующие пути pure, например 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, могут не работать в старых версиях.