Миграции¶

Команды¶

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

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

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

Эта структура в памяти также используется для определения различий между вашими моделями и текущим состоянием ваших миграций; Django выполняет все изменения в наборе моделей в памяти, чтобы определить состояние ваших моделей в последний раз, когда вы запускали makemigrations. Затем он использует эти модели для сравнения с моделями в ваших файлах 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, сериализуются в миграциях, поэтому функции и классы должны быть сохранены пока есть ссылающаяся на них миграция. Любые :doc:`пользовательские поля модели </howto/custom-model-fields> также необходимо сохранить, так как они импортируются напрямую путем миграции.

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

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

Рекомендации при удалении полей модели¶

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

Чтобы помочь в этой ситуации, Django предоставляет некоторые атрибуты полей модели, чтобы помочь с устареванием полей модели с помощью system check framework.

Добавьте атрибут 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 ожидает вызываемый объект в качестве аргумента, который принимает два аргумента - первый app registry, который имеет исторические версии всех ваших моделей, загруженные в него, соответствуют тому месту в вашей истории, где происходит миграция, а второй - это 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 и помещая их все по порядку, а затем запускает над ними оптимизатор, чтобы попытаться уменьшить длину списка - например, он знает, что CreateModel и DeleteModel отменяют друг друга, и он знает, что AddField можно свернуть в CreateModel.

После того, как последовательность операций была максимально сокращена - возможная сумма зависит от того, насколько тесно связаны ваши модели и есть ли у вас RunSQL или RunPython операции (которые не могут быть оптимизированы, если они не отмечены как elidable) - 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? [yN] 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, выделите один из ForeignKeys в цикле циклических зависимостей в отдельную миграцию и переместите с ним зависимость в другое приложение. Если вы не уверены, посмотрите, как 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 экземпляры (включая те, которые знают часовой пояс)
• экземпляры decimal.Decimal
• <<<экземпляры enum.Enum и enum.Flag
• экземпляры uuid.UUID
• Экземпляры 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, могут не работать в более старых версиях.