Операции над миграциями¶

CreateModel¶

class CreateModel(name, fields, options=None, bases=None, managers=None)[исходный код]¶

Создает новую модель в истории проекта и соответствующую таблицу в базе данных.

name - это название модели, которое должно быть записано в файле models.py.

fields - это список из двух кортежей (field_name, field_instance). Экземпляр поля должен быть несвязанным полем (как models.CharField(...), а не поле, взятое из другой модели).

options - это необязательный словарь значений из класса Meta модели.

base - это необязательный список других классов, от которых наследуется эта модель; он может содержать как объекты класса, так и строки в формате appname.ModelName, если вы хотите зависеть от другой модели (чтобы вы унаследовали от исторической версии). Если он не указан, по умолчанию он унаследован от стандартной модели models.Model.

managers принимает список из двух кортежей (manager_name, manager_instance). Первый менеджер в списке будет менеджером по умолчанию для этой модели во время миграции.

DeleteModel¶

class DeleteModel(name)[исходный код]¶

Удаляет модель из истории проекта и ее таблицу из базы данных.

RenameModel¶

class RenameModel(old_name, new_name)[исходный код]¶

Переименовывает модель со старого имени на новое.

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

AlterModelTable¶

class AlterModelTable(name, table)[исходный код]¶

Изменяет имя таблицы модели (параметр db_table в подклассе Meta).

AlterModelTableComment¶

class AlterModelTableComment(name, table_comment)[исходный код]¶

Изменяет комментарий таблицы модели (опция db_table_comment на подклассе Meta).

AlterUniqueTogether¶

class AlterUniqueTogether(name, unique_together)[исходный код]¶

Изменяет набор уникальных ограничений модели (параметр unique_together в подклассе Meta).

AlterIndexTogether¶

class AlterIndexTogether(name, index_together)[исходный код]¶

Изменяет набор пользовательских индексов модели (опция index_together на подклассе Meta).

AlterOrderWithRespectTo¶

class AlterOrderWithRespectTo(name, order_with_respect_to)[исходный код]¶

Создает или удаляет столбец _order, необходимый для параметра order_with_respect_to в подклассе Meta.

AlterModelOptions¶

class AlterModelOptions(name, options)[исходный код]¶

Сохраняет изменения различных параметров модели (настройки в Meta модели), например permissions и verbose_name. Не влияет на базу данных, но сохраняет эти изменения для использования экземпляров RunPython. options должен быть словарём, отображающим имена опций для значений.

AlterModelManagers¶

class AlterModelManagers(name, managers)[исходный код]¶

Изменяет менеджеров, доступных во время миграции.

AddField¶

class AddField(model_name, name, field, preserve_default=True)[исходный код]¶

Добавляет поле в модель. model_name - это имя модели, name - имя поля, а field - несвязанный экземпляр Field (то, что вы бы поместили в объявление поля в models.py - например, models.IntegerField(null=True).

Аргумент preserve_default указывает, является ли значение поля по умолчанию постоянным и должно ли оно быть записано в состояние проекта (True), или оно является временным и только для этой миграции (False) - обычно потому что миграция добавляет в таблицу поле, не допускающее значения NULL, и требует значения по умолчанию для помещения в существующие строки. Это не влияет на поведение установки значений по умолчанию в базе данных напрямую - Django никогда не устанавливает значения по умолчанию для базы данных и всегда применяет их в коде Django ORM.

RemoveField¶

class RemoveField(model_name, name)[исходный код]¶

Удаляет поле из модели.

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

AlterField¶

class AlterField(model_name, name, field, preserve_default=True)[исходный код]¶

Изменяет определение поля, включая изменения его типа, null, unique, db_column и другие атрибуты поля.

Аргумент preserve_default указывает, является ли значение поля по умолчанию постоянным и должно ли оно быть записано в состояние проекта (True), или оно временное и предназначено только для этой миграции (False) - обычно потому что миграция изменяет поле, допускающее значение NULL, на поле, не допускающее значения NULL, и требует значения по умолчанию для помещения в существующие строки. Это не влияет на поведение установки значений по умолчанию в базе данных напрямую - Django никогда не устанавливает значения по умолчанию для базы данных и всегда применяет их в коде Django ORM.

Обратите внимание, что не все изменения возможны во всех базах данных - например, вы не можете изменить поле текстового типа, такое как models.TextField(), в поле числового типа, например models.IntegerField() в большинстве базы данных.

RenameField¶

class RenameField(model_name, old_name, new_name)[исходный код]¶

Изменяет имя поля (и, если не задано db_column, имя его столбца).

AddIndex¶

class AddIndex(model_name, index)[исходный код]¶

Создает индекс в таблице базы данных для модели с именем model_name. index - это экземпляр класса Index.

RemoveIndex¶

class RemoveIndex(model_name, name)[исходный код]¶

Удаляет индекс с именем name из модели с model_name.

RenameIndex¶

class RenameIndex(model_name, new_name, old_name=None, old_fields=None)[исходный код]¶

Переименовывает индекс в таблице базы данных для модели с model_name. Может быть задано ровно одно из old_name и old_fields. old_fields - это итерабельность строк, часто соответствующих полям index_together.

В базах данных, которые не поддерживают оператор переименования индекса (SQLite и MariaDB < 10.5.2), операция будет удалена и создана заново, что может быть дорогостоящим.

AddConstraint¶

class AddConstraint(model_name, constraint)[исходный код]¶

Создает constraint в таблице базы данных для модели с именем model_name.

RemoveConstraint¶

class RemoveConstraint(model_name, name)[исходный код]¶

Удаляет ограничение с именем name из модели с model_name.

RunSQL¶

class RunSQL(sql, reverse_sql=None, state_operations=None, hints=None, elidable=False)[исходный код]¶

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

sql и reverse_sql, если они указаны, должны быть строками SQL для запуска в базе данных. В большинстве бэкэндов баз данных (всех, кроме PostgreSQL) Django разбивает SQL на отдельные операторы перед их выполнением.

Вы также можете передать список строк или двух кортежей. Последний используется для передачи запросов и параметров так же, как cursor.execute(). Эти три операции эквивалентны:

migrations.RunSQL("INSERT INTO musician (name) VALUES ('Reinhardt');")
migrations.RunSQL([("INSERT INTO musician (name) VALUES ('Reinhardt');", None)])
migrations.RunSQL([("INSERT INTO musician (name) VALUES (%s);", ["Reinhardt"])])

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

Запросы reverse_sql выполняются, когда миграция не применяется. Они должны отменить то, что делают запросы sql. Например, чтобы отменить указанную выше вставку с удалением:

migrations.RunSQL(
    sql=[("INSERT INTO musician (name) VALUES (%s);", ["Reinhardt"])],
    reverse_sql=[("DELETE FROM musician where name=%s;", ["Reinhardt"])],
)

Если reverse_sql равно None (по умолчанию), операция RunSQL необратима.

Аргумент state_operations позволяет вам предоставлять операции, эквивалентные SQL с точки зрения состояния проекта. Например, если вы вручную создаете столбец, вы должны передать сюда список, содержащий операцию AddField, чтобы автодетектор по-прежнему имел актуальное состояние модели. Если вы этого не сделаете, при следующем запуске makemigrations он не увидит никаких операций, добавляющих это поле, и попытается запустить его снова. Например:

migrations.RunSQL(
    "ALTER TABLE musician ADD COLUMN name varchar(255) NOT NULL;",
    state_operations=[
        migrations.AddField(
            "musician",
            "name",
            models.CharField(max_length=255),
        ),
    ],
)

Необязательный аргумент hints будет передан как **hints в метод allow_migrate() маршрутизаторов баз данных, чтобы помочь им в принятии решений о маршрутизации. Смотрите Подсказки для получения более подробной информации о подсказках базы данных.

Необязательный аргумент elidable определяет, будет ли операция удалена (исключена), при сжатии миграций.

RunSQL.noop¶

Передайте атрибут RunSQL.noop параметру sql или reverse_sql, если вы хотите, чтобы операция ничего не делала в заданном направлении. Это особенно полезно для того, чтобы сделать операцию обратимой.

RunPython¶

class RunPython(code, reverse_code=None, atomic=None, hints=None, elidable=False)[исходный код]¶

Запускает собственный код Python в историческом контексте. code (и reverse_code, если он указан) должны быть вызываемыми объектами, которые принимают два аргумента; первый - это экземпляр django.apps.registry.Apps, содержащий исторические модели, которые соответствуют месту операции в истории проекта, а второй - экземпляр SchemaEditor.

Аргумент reverse_code вызывается, когда миграции не применяются. Этот вызываемый объект должен отменить то, что сделано в вызываемом code, чтобы миграция была обратимой. Если reverse_code равен None (по умолчанию), операция RunPython необратима.

Необязательный аргумент hints будет передан как **hints в метод allow_migrate() маршрутизаторов баз данных, чтобы помочь им принять решение о маршрутизации. Смотрите Подсказки для получения более подробной информации о подсказках базы данных.

Необязательный аргумент elidable определяет, будет ли операция удалена (исключена), при сжатии миграций.

Рекомендуется написать код как отдельную функцию над классом Migration в файле миграции и передать его в RunPython. Вот пример использования RunPython для создания некоторых начальных объектов в модели Country:

from django.db import migrations


def forwards_func(apps, schema_editor):
    # We get the model from the versioned app registry;
    # if we directly import it, it'll be the wrong version
    Country = apps.get_model("myapp", "Country")
    db_alias = schema_editor.connection.alias
    Country.objects.using(db_alias).bulk_create(
        [
            Country(name="USA", code="us"),
            Country(name="France", code="fr"),
        ]
    )


def reverse_func(apps, schema_editor):
    # forwards_func() creates two Country instances,
    # so reverse_func() should delete them.
    Country = apps.get_model("myapp", "Country")
    db_alias = schema_editor.connection.alias
    Country.objects.using(db_alias).filter(name="USA", code="us").delete()
    Country.objects.using(db_alias).filter(name="France", code="fr").delete()


class Migration(migrations.Migration):
    dependencies = []

    operations = [
        migrations.RunPython(forwards_func, reverse_func),
    ]

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

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

По умолчанию RunPython запускает свое содержимое внутри транзакции в базах данных, которые не поддерживают транзакции DDL (например, MySQL и Oracle). Это должно быть безопасно, но может вызвать сбой, если вы попытаетесь использовать schema_editor, предоставленный этими бэкэндами; в этом случае передайте atomic=False операции RunPython.

В базах данных, которые действительно поддерживают транзакции DDL (SQLite и PostgreSQL), операции RunPython не содержат автоматически добавляемых транзакций, кроме транзакций, созданных для каждой миграции. Таким образом, в PostgreSQL, например, вам следует избегать объединения изменений схемы и операций RunPython в одной миграции, иначе вы можете столкнуться с такими ошибками, как OperationalError: невозможно ALTER TABLE "mytable", потому что у него есть отложенные триггерные события.

Если у вас другая база данных и вы не уверены, поддерживает ли она транзакции DDL, проверьте атрибут django.db.connection.features.can_rollback_ddl.

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

static RunPython.noop()[исходный код]¶

Передайте метод RunPython.noop в code или reverse_code, если вы хотите, чтобы операция ничего не делала в заданном направлении. Это особенно полезно для того, чтобы сделать операцию обратимой.

SeparateDatabaseAndState¶

class SeparateDatabaseAndState(database_operations=None, state_operations=None)[исходный код]¶

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

Он принимает два списка операций. Когда его попросят применить состояние, он будет использовать список state_operations (это обобщенная версия аргумента state_operations в RunSQL). Когда вас попросят применить изменения к базе данных, он будет использовать список database_operations.

Если фактическое состояние базы данных и представление состояния Django не синхронизируются, это может нарушить структуру миграции и даже привести к потере данных. Стоит проявлять осторожность и тщательно проверять свою базу данных и операции состояния. Вы можете использовать sqlmigrate и dbshell для проверки операций вашей базы данных. Вы можете использовать makemigrations, особенно с --dry-run, чтобы проверить свои операции с состоянием.

Пример использования SeparateDatabaseAndState смотрите в разделе change-a-manytomanyfield-to-use-a-through-model.