Всем привет! Меня зовут Макс, я Lead Backend и автор YouTube-канала PyLounge. 

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

В этом же материале поговорим о самом интересном: что происходит, когда python manage.py migrate запускается в 17:30 в пятницу на проде, под 3k RPS и таблицей в 200 миллионов строк. 

Расскажу какие блокировки в PostgreSQL берёт каждая операция Django, что внутри atomic = False, как пишется правильный паттерн expand - migrate - contract, зачем нужны AddIndexConcurrently, AddConstraintNotValid, SeparateDatabaseAndState и как обновлять данные на больших таблицах.

P.S. примеры намеренно упрощены, чтобы влезли в статью и не задушили. В реальной жизни всё ещё хуже - но шаги те же.

P.S.S. При подготовки этого материала ни одна продовая база данных не пострадала. 

Почему migrate в проде это не "просто одна команда"

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

1. Сгенерированный SQL. Иногда не такой, который ты ожидал. Например, AlterField(max_length=64)для CharField(max_length=32) - это ALTER TABLE ... ALTER COLUMN TYPE varchar(64), и, да, на PostgreSQL это будет очень быстро. 

А вот некоторые изменения типа действительно приводят к переписыванию всей таблицы (table rewrite), например, text -> integer, varchar -> numeric, json -> jsonb и другие небинарно-совместимые преобразования.

При этом varchar(n) -> text в PostgreSQL rewrite не требует - это binary-compatible изменение и обычно выполняется как metadata-only операция.

2. Блокировки. PostgreSQL может блокировать таблицу так, что не пройдет даже SELECT. Очереди блокировок в PostgreSQL - это FIFO. То есть твоя миграция ждет долгую транзакцию пять минут, а за ней молча стоят ещё 200 запросов от пользователей. Никто не отвечает. Прод R.I.P.

3. Python-код в RunPython. Он запускается прямо в транзакции миграции (если atomic = True, а это значение по умолчанию) и держит её открытой всё время выполнения. Developer.objects.all().update(...) на 50 миллионов строк - R.I.P.

Из практики (все персонажи и числа выдуманы, я актер, это все постановка):

• Кейс 1. Славик добавил поле is_archived =models.BooleanField(default=False) 
  в таблицу с 80 000 000 строк на PostgreSQL 13. Миграция отработала за 14 минут. Всё это время таблица была недоступна на запись. Прод лежал, весь автобус плакал. 

• Кейс 2. Владислав добавил models.Index(fields=['created_at']) в Meta модели Order.  CREATE INDEX без CONCURRENTLYвзял SHARE на таблице - все вставки заказов встали в очередь на десять минут. 

• Кейс 3. Васян написал data-миграцию для бэкфилла на 20M строк через Order.objects.filter(...).update(...). Миграция была атомарной по умолчанию. Один большой UPDATE сгенерил гигантский WAL, реплики залагали - R.I.P согласованность данных.

Все три случая лечатся одинаково - понимать, что именно делает каждая твоя миграция на уровне PostgreSQL.

Минимально необходимая теория блокировок в PostgreSQL

PostgreSQL имеет 8 уровней табличных блокировок. Запомнить все не обязательно - достаточно понять "лестницу": чем выше уровень, тем больше других операций он блокирует. Уровни в иерархии (от слабого к сильному):

1. ACCESS SHARE - берет SELECT. Самая слабая блокировка: обычное чтение почти никому не мешает и конфликтует только с ACCESS EXCLUSIVE.

4. ROW SHARE - SELECT FOR UPDATE/SHARE. Используется, когда запрос собирается блокировать строки; чуть строже обычного чтения.

5. ROW EXCLUSIVE - INSERT, UPDATE, DELETE. Это стандартная DML-нагрузка: изменения данных разрешены параллельно, пока нет «тяжёлого» DDL. То есть обычные DML-операции не мешают друг другу, но серьёзные изменения структуры таблицы могут остановить или заблокировать их (REINDEX, ALTER TABLE ... TYPE, ALTER TABLE ... ADD COLUMN и т.д.).

6. SHARE UPDATE EXCLUSIVE - VACUUM (без FULL), ANALYZE, CREATE INDEX CONCURRENTLY, ALTER TABLE VALIDATE CONSTRAINT, REINDEX CONCURRENTLY. Нужна для риалтайм-операций обслуживания: таблицу можно продолжать читать и менять.

7. SHARE - CREATE INDEX (без CONCURRENTLY). Разрешает чтение, но блокирует INSERT/UPDATE/DELETE, потому что индекс строится в одном консистентном состоянии.

8. SHARE ROW EXCLUSIVE - CREATE TRIGGER, некоторые ALTER TABLE. Более жёсткий DDL-режим: PostgreSQL защищает структуру таблицы от параллельных изменений.

9. EXCLUSIVE - REFRESH MATERIALIZED VIEW CONCURRENTLY. Почти полная блокировка: читать можно, но любые изменения данных запрещены.

10. ACCESS EXCLUSIVE - DROP TABLE, TRUNCATE, большинство ALTER TABLE, REINDEX. Самая сильная блокировка: останавливает вообще всё, включая обычный SELECT.

Для миграций нас в основном волнует разница между CONCURRENTLY-вариантами (SHARE UPDATE EXCLUSIVE - совместимо с DML) и обычными DDL (SHARE / ACCESS EXCLUSIVE - НЕ совместимо с DML).

Великий и ужасный - ACCESS EXCLUSIVE

Эта блокировка берется:

• ALTER TABLE ... ADD COLUMN (даже если мгновенно).

• ALTER TABLE ... DROP COLUMN.

• ALTER TABLE ... ALTER COLUMN TYPE (даже без REWRITE).

• ALTER TABLE ... ADD CONSTRAINT (без NOT VALID).

• CREATE INDEX (без CONCURRENTLY) - берёт SHARE, что не полный ACCESS EXCLUSIVE, но всё равно блокирует write.

• DROP INDEX (без CONCURRENTLY).

• ALTER TABLE ... RENAME.

• DROP TABLE, TRUNCATE, CLUSTER, VACUUM FULL.

ACCESS EXCLUSIVE мгновенен, если операция не требует физического переписывания таблицы или сканирования всех строк. Например, ADD COLUMN без default - это просто изменение метаданных в pg_attribute, миллисекунды. Но даже мгновенная ACCESS EXCLUSIVE может уронить прод из-за очереди блокировок.

Очередь блокировок и почему она опасна

PostgreSQL старается не допускать ситуации, когда более сильные блокировки ждут бесконечно долго. Поэтому если ALTER TABLE уже ждёт ACCESS EXCLUSIVE, новые запросы, которые формально совместимы с текущими lock'ами, могут начать вставать в очередь за ним.

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

Сценарий:

T0: Аналитик запустил SELECT pg_dump таблицы users → берёт ACCESS SHARE на 5 минут.

T1: Запускается миграция ALTER TABLE users ADD COLUMN foo
    -> пытается взять ACCESS EXCLUSIVE -> ждёт.

T2: Пришёл API-запрос: SELECT * FROM users WHERE id = 42
    -> пытается взять ACCESS SHARE -> совместим с тем, что у аналитика,
       НО несовместим с тем, что ЖДЁТ миграция -> встаёт в очередь.

T3: Ещё 200 запросов -> все в очереди.

T4: Аналитик закончил.

T5: Миграция отработала за 5 мс.

T6: Очередь рассасывается.

Между T1 и T5 прошло 5 минут полной недоступности сервиса. Миграция при этом фактически отработала за 5 мс.

Лечение - lock_timeout. Это настройка PostgreSQL, которая говорит "если не могу взять блокировку за N секунд - упади". Лучше упасть и попробовать снова через минуту, чем стоять и блокировать прод:

# 0042_safe_alter.py
from django.db import migrations


class Migration(migrations.Migration):
    atomic = False

    dependencies = [...]

    operations = [
        migrations.RunSQL(
            sql="SET lock_timeout = '3s'; SET statement_timeout = '5min';",
            reverse_sql=migrations.RunSQL.noop,
        ),
        # ... основные операции
    ]

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

Конкретные значения timeout'ов сильно зависят от вашей текущей нагрузки.

Для высоконагруженных систем 3 с. может быть слишком агрессивным значением и приводить к постоянным рестартам.

Timeout'ы стоит подбирать исходя из:

• средней длительности транзакций;

• профиля нагрузки;

• maintenance window;

• replication lag;

• количества параллельных записей.

statement_timeout - соседний предохранитель - "если сам SQL-стейтмент выполняется дольше N - упади".

В PostgreSQL 17 появился ещё один уровень - transaction_timeout. Он ограничивает время всей транзакции, не отдельного оператора.

migrations.RunSQL(
    sql=(
        "SET lock_timeout = '3s'; "
        "SET statement_timeout = '5min'; "
        "SET transaction_timeout = '10min';"  # PG 17+
    ),
    reverse_sql=migrations.RunSQL.noop,
),

sqlmigrate - твой лучший друг перед migrate

Перед каждым накатом миграции на прод запускаем:

python manage.py sqlmigrate developers 0042

И читаем глазами. Команда показывает SQL, который Django сгенерирует, не применяя его. Это первая и обязательная проверка. По нему ты сразу видишь:

• сколько операторов будет выполнено;

• есть ли ALTER TABLE ... ALTER COLUMN TYPE (потенциально REWRITE);

• есть ли CREATE INDEX без CONCURRENTLY;

• есть ли ADD CONSTRAINT без NOT VALID;

• завернет ли Django все в BEGIN ... COMMIT (если миграция атомарная).

Пример "опасного" вывода:

BEGIN;
--
-- Alter field rating on developer
--
ALTER TABLE "developers_developer" ALTER COLUMN "rating" TYPE numeric(10, 2)
    USING "rating"::numeric(10, 2);
COMMIT;

ALTER COLUMN ... TYPE ... USING ... - это REWRITE на всю таблицу под ACCESS EXCLUSIVE. На таблице в 50М строк это часы простоя.

Пример "безопасного":

BEGIN;
--
-- Add field nickname to developer
--
ALTER TABLE "developers_developer" ADD COLUMN "nickname" varchar(64) NULL;
COMMIT;

ACCESS EXCLUSIVE, но мгновенный (только метаданные). Безопасно, если есть lock_timeout.

Каталог операций х безопасность

Шпаргалка, на которую можно +-ориентироваться. 

P.S. Не является строгой спецификаций, это больше шпаргалка для общего понимая. Что можно держать в голове. 

Разберём ключевые ячейки подробнее.

AddField + DEFAULT на PostgreSQL 14+

# PG 14+ (и даже 11+), БЕЗОПАСНО:
migrations.AddField(
    model_name='developer',
    name='is_archived',
    field=models.BooleanField(default=False),
),

Эта миграция мгновенна на любой таблице. ACCESS EXCLUSIVE берётся, но удерживается миллисекунды.

Но! Это работает только для константных default. Если default - это callable, оптимизация PG не применяется и таблица переписывается:

# ОПАСНО на любом PG:
migrations.AddField(
    model_name='developer',
    name='external_id',
    field=models.UUIDField(default=uuid.uuid4),
),

Лечение - разделить на этапы:

1. AddField(null=True) - без default.

2. RunPython(backfill_uuid) чанками с atomic=False.

3. AlterField(null=False) - через AddConstraintNotValid + ValidateConstraint (см. ниже).

AddField + FK на большой таблице

ADD CONSTRAINT FOREIGN KEY валидирует существующие строки и может долго сканировать таблицу.

Основная проблема здесь - не столько тип блокировки, сколько длительность validation scan на больших таблицах. Во время валидации PostgreSQL берёт несколько lock'ов на referencing/referenced tables, а сама операция может идти очень долго на десятках миллионов строк. На таблице в 100M строк это может занять часы.

Решение - NOT VALID + VALIDATE CONSTRAINT. Django не имеет встроенной операции для FK с NOT VALID, поэтому делаем руками через RunSQL + SeparateDatabaseAndState:

class Migration(migrations.Migration):
    atomic = False

    dependencies = [...]

    operations = [
        # 1. Колонка nullable, мгновенно.
        migrations.AddField(
            model_name='order',
            name='customer',
            field=models.ForeignKey(
                'customers.Customer', null=True,
                on_delete=models.PROTECT, db_constraint=False,
            ),
        ),
        # 2. Добавляем FK как NOT VALID - мгновенно (берёт ACCESS EXCLUSIVE,
        #    но не сканирует таблицу).
        migrations.RunSQL(
            sql=(
                'ALTER TABLE "orders_order" '
                'ADD CONSTRAINT "orders_order_customer_fk" '
                'FOREIGN KEY ("customer_id") '
                'REFERENCES "customers_customer" ("id") NOT VALID;'
            ),
            reverse_sql=(
                'ALTER TABLE "orders_order" DROP CONSTRAINT "orders_order_customer_fk";'
            ),
        ),
        # 3. Валидируем существующие строки - SHARE UPDATE EXCLUSIVE,
        #    совместимо с DML, может идти долго, но прод работает.
        migrations.RunSQL(
            sql='ALTER TABLE "orders_order" VALIDATE CONSTRAINT "orders_order_customer_fk";',
            reverse_sql=migrations.RunSQL.noop,
        ),
    ]

VALIDATE CONSTRAINT обычно совместим с обычным DML и значительно безопаснее прямого ADD CONSTRAINT.

Но на очень горячих таблицах validation всё равно может создавать заметную IO-нагрузку и влиять на latency.

db_constraint=False в ForeignKey. Это говорит Django - в БД constraint не создавай, я его сделаю руками.

AlterConstraint - подарок от Django 5.2

Это маленькая, но очень важная для прода фича. Раньше любое изменение метаданных constraint - например, добавление violation_error_message для красивого сообщения юзеру при нарушении уникальности - приводило к миграции вида «DROP CONSTRAINT + ADD CONSTRAINT». На большой таблице это DROP INDEX + CREATE INDEX = боль.

Начиная с Django 5.2:

# Было в модели:
class Meta:
    constraints = [
        models.UniqueConstraint(fields=['email'], name='user_email_uniq'),
    ]

# Стало:
class Meta:
    constraints = [
        models.UniqueConstraint(
            fields=['email'], name='user_email_uniq',
            violation_error_message='Email уже занят',
        ),
    ]

В Django 5.1 и ранее makemigrations сгенерил бы RemoveConstraint + AddConstraint с реальным DROP/CREATE в БД. В Django 5.2 - AlterConstraint (no-op для БД, обновление только in-memory state):

# Django 5.2 makemigrations:
operations = [
    migrations.AlterConstraint(
        model_name='user',
        name='user_email_uniq',
        constraint=models.UniqueConstraint(
            fields=['email'], name='user_email_uniq',
            violation_error_message='Email уже занят',
        ),
    ),
]

Никакого ALTER TABLE. Просто Django запоминает новые метаданные. Минус одна потенциально долгая миграция - это здорово.

Главный паттерн: Expand - Migrate - Contract

Принцип 1: Старый код должен работать с новой схемой. 
Принцип 2: Новый код должен работать со старой схемой. 
Принцип 3: Между ними - отдельные шаги по миграции данных.

Это значит, что почти любое "опасное" изменение схемы - это не одна миграция и не один деплой. Это последовательность из 3+ релизов:

4. Expand. Расширяем схему так, чтобы старый код продолжал работать (новые поля nullable, новые таблицы не используются, старые поля остаются).

5. Migrate. Переводим логику и данные на новую схему. Обычно - несколько подэтапов с код-релизами между ними.

6. Contract. Удаляем старое.

Между этими этапами - обязательно деплои с проверкой, что всё работает. Никогда не пытайся уместить переименование поля в один PR.

Сквозной пример: переименование Developer.title в Developer.name

Это та же модель, что в первых статьях. Допустим, мы решили, что title - плохое имя для имени разработчика, нужно переименовать в name. Сделать это в лоб через RenameField значит:

• На уровне PG: ALTER TABLE RENAME COLUMN - мгновенно, ACCESS EXCLUSIVE.

• На уровне приложения: между моментом, когда миграция применилась, и моментом, когда задеплоился новый код, старые инстансы приложения ходят в БД с запросом SELECT title FROM developers_developer и получают ошибку column "title" does not exist.

В rolling deploy это особенно весело: пока новые поды поднимаются, старые продолжают отдавать 500-ки.

Правильный путь через 3 релиза:

Релиз 1 (Expand): добавляем name, оставляем title.

# developers/models.py
class Developer(models.Model):
    title = models.CharField(max_length=64)           # старое поле
    name = models.CharField(max_length=64, null=True) # новое поле

    @property
    def display_name(self):
        return self.name or self.title

Миграция 1 - schema:

class Migration(migrations.Migration):
    dependencies = [('developers', '0041_previous')]
    operations = [
        migrations.AddField(
            model_name='developer',
            name='name',
            field=models.CharField(max_length=64, null=True),
        ),
    ]

Миграция 2 - data (отдельной миграцией, не в одном файле!):

def copy_title_to_name(apps, schema_editor):
    Developer = apps.get_model('developers', 'Developer')
    db_alias = schema_editor.connection.alias
    from django.db.models import F

    BATCH_SIZE = 5000
    last_pk = 0

    while True:
        # Забираем очередной блок первичных ключей, строго pk > last_pk
        chunk = list(
            Developer.objects.using(db_alias)
            .filter(name__isnull=True, pk__gt=last_pk)
            .order_by('pk')
            .values_list('pk', flat=True)[:BATCH_SIZE]
        )

        if not chunk:
            break

        # Обновляем ровно этот блок
        (
            Developer.objects.using(db_alias)
            .filter(pk__in=chunk)
            .update(name=F('title'))
        )

        # Двигаем курсор
        last_pk = chunk[-1]


class Migration(migrations.Migration):
    atomic = False  # обязательно — батчи коммитятся независимо

    dependencies = [('developers', '0042_add_name_field')]
    operations = [
        migrations.RunPython(
            copy_title_to_name,
            reverse_code=migrations.RunPython.noop,
            elidable=True,  # при squash удалится — это разовая операция
        ),
    ]

Не собирай PK всей таблицы в Python-список (list(qs.values_list(...))) на десятках миллионов строк легко приводит к огромному потреблению памяти.

Для больших таблиц безопаснее keyset pagination (pk > last_pk) или cursor-based batching.

order_by('pk') + pk__gt=last_pk позволяет стабильно и предсказуемо проходить таблицу небольшими чанками без материализации всего набора строк в памяти Python-процесса.

Для реально огромной таблицы даже пример выше необходимо будет оптимизировать

В коде приложения продолжаем читать title, но при создании/обновлении пишем в оба поля:

def update_developer(developer: Developer, new_title: str) -> None:
    developer.title = new_title
    developer.name = new_title
    developer.save(update_fields=['title', 'name'])

Это позволит старым инстансам читать title, а новым - name. Бэкфилл закроет существующие строки.

Релиз 2 (Migrate): переключаем чтение на name.

После того как релиз 1 деплоится и бэкфилл проходит - в новой версии кода:

class Developer(models.Model):
    title = models.CharField(max_length=64)
    name = models.CharField(max_length=64, null=True)

    @property
    def display_name(self):
        return self.name  # больше не fallback на title

Пишем в оба поля (на случай отката), читаем только из name.

Релиз 3 (Contract): удаляем title.

В коде убираем title совсем. Делаем name обязательным.

class Developer(models.Model):
    name = models.CharField(max_length=64)  # теперь NOT NULL

Миграция:

operations = [
    # На этот момент 100% строк имеют name, проверяем CHECK NOT VALID + VALIDATE.
    AddConstraintNotValid(...),
    ValidateConstraint(...),
    migrations.AlterField(
        model_name='developer',
        name='name',
        field=models.CharField(max_length=64),  # null=False
    ),
    migrations.RemoveField(
        model_name='developer',
        name='title',
    ),
]

Да, три релиза вместо одного. Зато 0 минут даунтайма.

Антипаттерн: давайте просто RenameField

Иногда соблазнительно:

operations = [
    migrations.RenameField(
        model_name='developer',
        old_name='title',
        new_name='name',
    ),
]

makemigrations даже спросит: "It looked like you renamed title to name. Is that correct?" - yes. 

Для rolling deploy и distributed environments такой подход опасен без обратной совместимости. В controlled deployment сценариях (blue-green deploy) RenameField может быть вполне допустим.

PostgreSQL-специфичные операции Django

В django.contrib.postgres.operations лежит небольшой, но критически важный набор операций, который автогенерация Django никогда не предложит сама. Их нужно вставлять руками.

AddIndexConcurrently и RemoveIndexConcurrently

CREATE INDEX без CONCURRENTLY берёт SHARE на таблице - это значит, что INSERT/UPDATE/DELETE встают в очередь. На таблице, в которую активно пишут, такой AddIndex = гарантированный инцидент.

CONCURRENTLY обходит блокировку, читая таблицу в несколько проходов. Цена: индекс создаётся в 2-3 раза дольше и не может выполняться внутри транзакции.

from django.contrib.postgres.operations import (
    AddIndexConcurrently, RemoveIndexConcurrently,
)
from django.db import migrations, models


class Migration(migrations.Migration):
    atomic = False  # обязательно — CONCURRENTLY вне транзакции

    dependencies = [('developers', '0044_some_migration')]

    operations = [
        AddIndexConcurrently(
            model_name='developer',
            index=models.Index(
                fields=['rating'],
                name='developer_rating_idx',
            ),
        ),
    ]

Подвох: если CREATE INDEX CONCURRENTLY упадёт посередине (например, по lock_timeout или из-за дубликата в unique-индексе), индекс останется в БД со статусом INVALID. Он виден в \d table и pg_indexes, но не используется планировщиком. Django об этом ничего не знает.

Лечение - перед повторным накатом проверить и удалить:

-- Найти INVALID-индексы:
SELECT indexrelid::regclass AS index_name, indrelid::regclass AS table_name
FROM pg_index
WHERE indisvalid = false;

-- Удалить:
DROP INDEX CONCURRENTLY IF EXISTS developer_rating_idx;

И после этого перезапустить миграцию.

AddConstraintNotValid + ValidateConstraint

Появились в Django 4.0 для PostgreSQL. Только для CheckConstraint (для FK - руками через RunSQL, как мы делали выше).

Обычный ADD CONSTRAINT ... CHECK блокирует таблицу под ACCESS EXCLUSIVE и сканирует все строки. На 50M строк это надолго.

NOT VALID говорит: не сканируй существующие, проверяй только новые INSERT/UPDATE. Берёт ACCESS EXCLUSIVE, но мгновенно. Потом отдельной операцией валидируем существующие - это идёт под SHARE UPDATE EXCLUSIVE (совместимо с DML).

from django.contrib.postgres.operations import AddConstraintNotValid, ValidateConstraint
from django.db import migrations, models


# Файл 0045_add_rating_constraint_not_valid.py
class Migration(migrations.Migration):
    dependencies = [('developers', '0044_previous')]
    operations = [
        AddConstraintNotValid(
            model_name='developer',
            constraint=models.CheckConstraint(
                condition=models.Q(rating__gte=0),  # ВАЖНО
                name='developer_rating_non_negative',
            ),
        ),
    ]


# ОТДЕЛЬНЫЙ файл 0046_validate_rating_constraint.py
class Migration(migrations.Migration):
    atomic = False  # VALIDATE может быть долгим

    dependencies = [('developers', '0045_add_rating_constraint_not_valid')]
    operations = [
        ValidateConstraint(
            model_name='developer',
            name='developer_rating_non_negative',
        ),
    ]

Важно про CheckConstraint: в Django 5.1+ параметр стал называться condition вместо check (старое имя deprecated, в 6.0 ещё работает с warning, но в будущем удалят). 

Важно про две миграции: если положить в одну, то транзакция вокруг них (atomic = True по умолчанию) сведёт всю оптимизацию на нет.

UniqueConstraint CONCURRENTLY: лайфхак через SeparateDatabaseAndState

Django не имеет AddConstraintConcurrently. Если нужно навесить UNIQUE на большую таблицу, обычный AddConstraint(UniqueConstraint(...)) создаст индекс под SHARE - а это write-блокировка.

Обход: создать UNIQUE INDEX CONCURRENTLY руками, а Django сказать считай, что constraint у меня есть через SeparateDatabaseAndState:

from django.db import migrations, models


class Migration(migrations.Migration):
    atomic = False

    dependencies = [('developers', '0046_previous')]

    operations = [
        migrations.SeparateDatabaseAndState(
            database_operations=[
                migrations.RunSQL(
                    sql=(
                        'CREATE UNIQUE INDEX CONCURRENTLY "developer_inn_uniq" '
                        'ON "developers_developer" ("inn");'
                    ),
                    reverse_sql=(
                        'DROP INDEX CONCURRENTLY IF EXISTS "developer_inn_uniq";'
                    ),
                ),
            ],
            state_operations=[
                migrations.AddConstraint(
                    model_name='developer',
                    constraint=models.UniqueConstraint(
                        fields=['inn'],
                        name='developer_inn_uniq',
                    ),
                ),
            ],
        ),
    ]

database_operations идут в БД (создаём индекс CONCURRENTLY), state_operations обновляют in-memory представление Django (autodetector думает, что constraint существует и не предлагает создать его снова).

PostgreSQL умеет использовать unique-индекс как backing для constraint поэтому такой подход корректен и с точки зрения семантики.

SeparateDatabaseAndState

SDAS - главный инструмент тонкой работы, когда автогенерация Django делает правильно по семантике, но не подходит по перформансу. Ещё несколько кейсов, где он нужен.

Кейс 1: переход с index_together на Meta.indexes

index_together deprecated в Django 4.2 и удалён в 5.1. Просто перенести в indexes нельзя - Django сгенерирует миграцию, которая пересоздаст индекс: DROP + CREATE. На большой таблице будет плохо.

Хитрость: оставить индекс в БД, но сказать Django, что мы "переименовали" его в state:

# Найти текущее имя индекса в БД:
# \d+ developers_developer в psql
# Или: SELECT indexname FROM pg_indexes WHERE tablename='developers_developer';
# Допустим, было developers_dev_a_b_idx.

# В Meta модели:
class Meta:
    indexes = [
        models.Index(fields=['a', 'b'], name='developers_dev_a_b_idx'),
    ]

# Миграция:
operations = [
    migrations.SeparateDatabaseAndState(
        database_operations=[],  # в БД ничего не делаем
        state_operations=[
            migrations.AlterIndexTogether(
                name='developer',
                index_together=set(),
            ),
            migrations.AddIndex(
                model_name='developer',
                index=models.Index(
                    fields=['a', 'b'],
                    name='developers_dev_a_b_idx',
                ),
            ),
        ],
    ),
]

Главное - указать то же имя, что у физического индекса в БД. Тогда Django считает, что всё в порядке, а реально индекс не трогался.

Кейс 2: переименование колонки через db_column

Альтернатива expand/contract для маленьких таблиц или внутренних рефакторингов: переименовать только в коде Python, оставив физическое имя колонки.

class Developer(models.Model):
    # В коде — name, в БД — title
    name = models.CharField(max_length=64, db_column='title')

Миграция:

operations = [
    migrations.SeparateDatabaseAndState(
        database_operations=[],
        state_operations=[
            migrations.RenameField(
                model_name='developer',
                old_name='title',
                new_name='name',
            ),
            migrations.AlterField(
                model_name='developer',
                name='name',
                field=models.CharField(max_length=64, db_column='title'),
            ),
        ],
    ),
]

Кейс 3: превращение M2M в явную through-модель

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

Через SeparateDatabaseAndState мы оставляем таблицу в БД, но говорим Django - вот теперь это твоя through-модель:

# В models.py — определяем through:
class Project(models.Model):
    developers = models.ManyToManyField(
        'developers.Developer',
        through='ProjectDeveloper',
    )

class ProjectDeveloper(models.Model):
    project = models.ForeignKey('Project', on_delete=models.CASCADE)
    developer = models.ForeignKey(
        'developers.Developer', on_delete=models.CASCADE,
    )

    class Meta:
        db_table = 'projects_project_developers'  # имя авто-таблицы M2M

SeparateDatabaseAndState - очень мощный, но опасный инструмент.

Он позволяет "разводить":

• реальное состояние БД;

• migration state Django.

При неаккуратном использовании это приводит к state drift, странным auto-generated migrations и трудноотлавливаемым проблемам в графе миграций.

Чем больше SDAS в проекте тем важнее дисциплина вокруг ревью миграций.

atomic = False

По умолчанию каждая миграция Django оборачивается в транзакцию (BEGIN ... COMMIT). Это безопасно для большинства операций: упала миграция - БД откатилась к исходному состоянию.

Но иногда атомарность не нужна и даже вредит:

• Операции с CONCURRENTLY вообще запрещены внутри транзакции.

• Долгий бэкфилл данных в одной транзакции = ROW EXCLUSIVE на куче строк надолго + раздутый WAL.

• AddConstraintNotValid + VALIDATE хотим выполнить независимо, чтобы VALIDATE мог идти на проде без блокировок.

В таких случаях ставим:

class Migration(migrations.Migration):
    atomic = False
    # ...

Что происходит при сбое в non-atomic миграции

Тонкий момент. В обычной (atomic) миграции при ошибке Django делает ROLLBACK - БД возвращается в исходное состояние, и запись в django_migrations не добавляется. Можно безопасно перезапустить.

В non-atomic при ошибке:

7. SQL, выполненные до места ошибки, остаются применёнными в БД (Django выполняет операции отдельными transaction scopes, поэтому часть операций может успеть примениться до места ошибки)

8. Запись в django_migrations не добавляется - Django не знает, что миграция применена частично.

9. При повторном запуске Django начнёт миграцию с самого начала и упадёт на первой же операции с column already exists / index already exists.

Как лечить:

Вариант 1: писать идемпотентные SQL руками. Это в первую очередь касается RunSQL:

migrations.RunSQL(
    sql='ALTER TABLE foo ADD COLUMN IF NOT EXISTS bar integer;',
    reverse_sql='ALTER TABLE foo DROP COLUMN IF EXISTS bar;',
),

К сожалению, Django-операции (AddField, AddIndex) не умеют генерить IF NOT EXISTS - для них этот трюк не работает.

Вариант 2: разбивать миграцию на максимально мелкие шаги. Если упадёт - упадёт на конкретном шаге, и руками легче понять, что сделалось, а что нет.

Вариант 3: ручная очистка перед перезапуском. Зашёл в psql, посмотрел \d table, удалил лишнее, повторил миграцию.

Вариант 4: --fake после ручного применения. Если ты руками докатил все, что нужно, скажи Django "считай, что миграция применена":

python manage.py migrate developers 0045 --fake

(--fake мы разбирали во второй статье)

Batch updates: data-миграции на больших таблицах

Один UPDATE на 50M строк это:

• ROW EXCLUSIVE на куче строк надолго;

• гигабайт WAL - реплики залагают;

• если в atomic = True = одна гигантская транзакция, увеличение размера shared buffers, autovacuum не может работать;

• невозможно прервать без отката.

PostgreSQL 17 содержит ряд заметных улучшений вокруг vacuum/WAL и обработке конкурентной нагрузки, но конкретный выигрыш сильно зависит от этой самой нагрузки и конфигурации системы. То есть это не значит, что можно теперь не думать про батчи - это значит, что последствия твоих ошибок проще пережить. Но писать всё равно надо нормально.

Лечение - батчи с atomic = False:

from django.db import migrations

def backfill_status(apps, schema_editor):
    Developer = apps.get_model('developers', 'Developer')
    db_alias = schema_editor.connection.alias

    BATCH_SIZE = 10_000

    qs = (
        Developer.objects.using(db_alias)
        .filter(status__isnull=True)
    )

    last_pk = 0

    while True:
        batch_qs = (
            qs.filter(pk__gt=last_pk)
               .order_by('pk')
        )

        # берём только границу диапазона
        batch = list(
            batch_qs.values_list('pk', flat=True)[:BATCH_SIZE]
        )

        if not batch:
            break

        start = batch[0]
        end = batch[-1]

        Developer.objects.using(db_alias).filter(
            pk__gte=start,
            pk__lte=end,
            status__isnull=True
        ).update(status='active')

        last_pk = end

class Migration(migrations.Migration):
    atomic = False

    dependencies = [('developers', '0050_add_status_field')]

    operations = [
        migrations.RunPython(
            backfill_status,
            reverse_code=migrations.RunPython.noop,
            elidable=True,
        ),
    ]

Несколько критичных моментов в этом коде:

10. apps.get_model(...), а не прямой импорт модели. Мы это обсуждали во второй статье. Импортированная модель - это "текущая" версия из models.py, в которой могут быть поля, ещё не существующие в БД. apps.get_model возвращает "историческую" модель - ровно такую, какой она была на момент этой миграции.

11. using(db_alias). На случай multi-db schema_editor.connection.alias отдаст нужное имя БД. Если забыть - update()пойдёт в default-базу.

12. reverse_code=migrations.RunPython.noop. Хорошо бы написать обратную функцию, но в случае бэкфилла это часто бессмысленно (исходного состояния "без статуса" больше не существует логически). noop говорит Django: "можешь откатить, никаких действий не нужно".

13. elidable=True. Бэкфилл - разовая операция. При squashmigrations Django удалит её из объединённой миграции.

14. atomic = False на уровне Migration. Без этого каждый .update() всё равно был бы внутри общей транзакции миграции - то есть мы бы не получили никакого выигрыша.

Когда лучше команда, а не миграция

Для очень больших бэкфиллов (>10M строк, часы выполнения) data-миграция - плохой выбор:

• Миграция блокирует выкатку. Если бэкфилл идёт 6 часов, релизы стоят.

• Миграцию нельзя поставить на паузу, перезапустить, мониторить отдельно.

• Если разработчик пропустит её локально (migrate идёт слишком долго)

Альтернатива - BaseCommand:

# developers/management/commands/backfill_developer_status.py
from django.core.management.base import BaseCommand
from django.db import transaction
from developers.models import Developer


class Command(BaseCommand):
    help = 'Backfill Developer.status'

    def add_arguments(self, parser):
        parser.add_argument('--batch-size', type=int, default=5000)
        parser.add_argument('--sleep', type=float, default=0.0)

    def handle(self, *args, batch_size, sleep, **options):
        import time

        qs = Developer.objects.filter(status__isnull=True)
        total = qs.count()
        self.stdout.write(f'To backfill: {total}')

        done = 0
        while True:
            pks = list(
                qs.order_by('pk').values_list('pk', flat=True)[:batch_size]
            )
            if not pks:
                break

            with transaction.atomic():
                Developer.objects.filter(pk__in=pks).update(status='active')

            done += len(pks)
            self.stdout.write(f'Done: {done}/{total}')
            if sleep:
                time.sleep(sleep)

Запускаем:

python manage.py backfill_developer_status --batch-size 2000 --sleep 0.5

Плюсы команды:

• запускаешь руками, когда нагрузка ниже;

• можешь прервать Ctrl+C и продолжить позже (она идемпотентна - берёт только строки с status IS NULL);

• параметры (batch_size, sleep) на лету;

• легко мониторить - отдельный процесс, отдельный лог.

Минус: нужно не забыть запустить руками.

NOT NULL без даунтайма: классический сценарий

Во второй статье мы разбирали, как пройти ошибку "You are trying to add a non-nullable field" при makemigrations. Сейчас тот же сценарий в production-разрезе.

Задача: у нас есть поле Developer.status, которое сейчас nullable, нужно сделать обязательным.

Наивный путь:

operations = [
    migrations.AlterField(
        model_name='developer',
        name='status',
        field=models.CharField(max_length=16),  # null=False
    ),
]

Что Django сгенерит:

ALTER TABLE "developers_developer" ALTER COLUMN "status" SET NOT NULL;

Эта операция берёт ACCESS EXCLUSIVE и сканирует всю таблицу для проверки, что нет NULL. На 50M строк = минуты простоя.

Безопасный путь — 4 шага:

Шаг 1: миграция — добавить CHECK (status IS NOT NULL) NOT VALID.

from django.contrib.postgres.operations import AddConstraintNotValid
from django.db import migrations, models


class Migration(migrations.Migration):
    dependencies = [('developers', '0050_previous')]
    operations = [
        AddConstraintNotValid(
            model_name='developer',
            constraint=models.CheckConstraint(
                condition=models.Q(status__isnull=False),
                name='developer_status_not_null',
            ),
        ),
    ]

После этой миграции новые строки уже не могут вставить NULL в status. Существующие - пока могут быть NULL, мы их не трогаем.

Шаг 2: код приложения пишет в status для всех новых записей.

Деплоим релиз. Теперь поток новых записей чист.

Шаг 3: data-миграция - бэкфиллим существующие строки.

def backfill_status(apps, schema_editor):
    # Как реализовано ранее


class Migration(migrations.Migration):
    atomic = False
    dependencies = [('developers', '0051_check_status_not_null')]
    operations = [
        migrations.RunPython(
            backfill_status,
            reverse_code=migrations.RunPython.noop,
            elidable=True,
        ),
    ]

Шаг 4: миграция — VALIDATE CONSTRAINT + AlterField.

from django.contrib.postgres.operations import ValidateConstraint
from django.db import migrations, models


class Migration(migrations.Migration):
    atomic = False  # VALIDATE может быть долгим

    dependencies = [('developers', '0052_backfill_status')]

    operations = [
        # 1. Валидируем CHECK — SHARE UPDATE EXCLUSIVE, совместимо с DML.
        ValidateConstraint(
            model_name='developer',
            name='developer_status_not_null',
        ),
        # 2. Меняем колонку на NOT NULL.
        # На PG 12+ при наличии валидного CHECK NOT NULL операция мгновенна:
        # PG использует существующий CHECK как доказательство.
        migrations.AlterField(
            model_name='developer',
            name='status',
            field=models.CharField(max_length=16),
        ),
        # 3. CHECK больше не нужен (его роль теперь у NOT NULL constraint).
        migrations.RemoveConstraint(
            model_name='developer',
            name='developer_status_not_null',
        ),
    ]

Django по умолчанию не сгенерит такую последовательность сам. makemigrations для смены null=True → null=Falseсоздаст обычный AlterField. Шаги 1, 3, 4 нужно писать руками; шаг 2 - обычная code-only data-миграция.

Тестирование миграций

Data-миграции - это код. Код должен иметь тесты. Без тестов миграция, отработавшая на 12 строках на dev, может рухнуть на 100M строк на проде.

Пакет django-test-migrations от wemake-services даёт удобный API:

from django_test_migrations.migrator import Migrator


def test_backfill_status_fills_existing_rows(transactional_db):
    migrator = Migrator(database='default')

    # 1. Применяем миграции до состояния "ДО" нашей data-миграции.
    old_state = migrator.apply_initial_migration(
        ('developers', '0050_add_status_field'),
    )
    Developer = old_state.apps.get_model('developers', 'Developer')

    # 2. Создаём данные — как они выглядели до бэкфилла.
    Developer.objects.create(title='Alice', status=None)
    Developer.objects.create(title='Bob', status=None)
    Developer.objects.create(title='Charlie', status='admin')

    # 3. Применяем нашу data-миграцию.
    new_state = migrator.apply_tested_migration(
        ('developers', '0052_backfill_status'),
    )
    Developer = new_state.apps.get_model('developers', 'Developer')

    # 4. Проверяем результат.
    assert Developer.objects.filter(status='unknown').count() == 2
    assert Developer.objects.filter(status='admin').count() == 1
    assert Developer.objects.filter(status__isnull=True).count() == 0

    migrator.reset()

Что полезного:

• Тест действительно прогоняет миграцию против БД, а не моки.

• Может тестировать reverse: применил A - создал данные - откатился до B - проверил, что данные адекватны.

• Интегрируется с pytest-django (фикстура transactional_db).

CI-минимум для миграций (чек-лист)

В каждом PR:

15. python manage.py makemigrations --check --dry-run - есть ли несгенерированные миграции в коде? Если разработчик поменял модели, но не запустил makemigrations, миграции в проде не будет.

16. python manage.py migrate --plan - что именно поедет.

17. Тесты на data-миграции (django-test-migrations).

18. (Опционально, для крупных проектов) - python manage.py sqlmigrate <app> <migration> в артефакт CI: ревьюверам удобно сразу увидеть SQL без поднятия локального окружения.

Чек-лист перед накатом миграции на прод

Бумажка над монитором. Перед каждой production-миграцией:

19. Запустил sqlmigrate, прочитал SQL глазами. Не смог понять глазами - прогнал нейронкой.

20. Понимаю, какую блокировку возьмёт PostgreSQL для каждой операции.

21. Если ACCESS EXCLUSIVE на большой таблице - миграция разделена на безопасные шаги (NOT VALID + VALIDATE, CONCURRENTLY, expand/contract).

22. Долгие операции в отдельной миграции с atomic = False.

23. Если есть сомнения - подумать над lock_timeout и statement_timeout

24. Изменения обратно-совместимы: старый код приложения корректно работает с новой схемой.

25. Есть план отката: если миграция сломала прод, что мы делаем? (Откатить миграцию? Откатить код? И то и другое?)

26. Есть бэкап актуальной БД, или это slave с актуальным lag.

27. На staging миграция прогналась против дампа prod-данных или их объёма.

28. Время накатывания - не пятница вечер. Не "вот сейчас релиз, и сразу миграция в пиковый трафик".

Если хоть один пункт не закрыт - лучше переложить накат или помолиться.

Экстра

Несколько подводных камней, которые не вписались в основное повествование, но регулярно стреляют:

• FK с CASCADE. ON DELETE CASCADE сам по себе не блокирует. Но DELETE родительской строки берёт ROW EXCLUSIVE на дочерних - на больших таблицах это медленно. 

• Изменение choices в Django обычно приводит к AlterField миграции, даже если схема БД фактически не меняется. На PostgreSQL лишние ALTER TABLE могут брать сильные блокировки, поэтому для часто меняющихся choices лучше использовать callable choices (Django 5.0+) либо state-only миграции через SeparateDatabaseAndState.

• max_length для varchar. Расширение мгновенно. Сужение - REWRITE. 

• AlterField для default. Изменение default=... в Python-коде модели не приводит к изменению default в БД - Django применяет default при INSERT на уровне Python. Но makemigrations всё равно сгенерит AlterField. Это no-op для БД, но лишний ALTER TABLE (мгновенный, но ACCESS EXCLUSIVE).

• Кейс с migrate --fake после non-atomic краха. Если ты руками докатил часть SQL, помни: --fake фиксирует запись в django_migrations, но не проверяет, действительно ли применены все операции. Ответственность за консистентность - на тебе. Лучше написать checklist в комментарии PR: "применил руками: ALTER TABLE X, CREATE INDEX Y; запускаю migrate --fake".

• Reverse data-миграций. По умолчанию ставим reverse_code=migrations.RunPython.noop - на reverse ничего не происходит. Это нормально для бэкфиллов: смысла откатывать данные нет. Для обратимых преобразований (например, миграции enum) - пишим явный reverse. Не оставляй RunPython без второго аргумента: Django выдаст ошибку при попытке откатить.

Заключение

Главные правила, которые стоит унести с собой:

• Перед migrate - sqlmigrate. Всегда. На любой миграции в любой ветке. Это бесплатно и спасает от 90% инцидентов.

• Малые шаги, отдельные миграции. В идеале одна миграция - одна логическая операция. NOT NULL - это четыре миграции, а не одна. Да, миграций станет много, но их можно будет сквошнуть.

• Expand - Migrate - Contract. Любое значимое изменение схемы - это минимум три релиза. Старый и новый код должны уметь работать с одной и той же БД.

• Автогенерация Django - стартовая точка, не финальная. На больших таблицах её надо править: SeparateDatabaseAndState, AddIndexConcurrently, AddConstraintNotValid, atomic = False.

• Инструменты-минимум: sqlmigrate + тесты data-миграций.

• Не забываем про существование  lock_timeout + statement_timeout

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

Буду рад фидбеку и кейсам из вашей практики в комментариях. А также замечаниям и исправлениям неточностей, который, вероятно, я мог допустить :)

Полезные ссылки

Документация PostgreSQL:

• Explicit Locking

• ALTER TABLE

• CREATE INDEX CONCURRENTLY

Пакеты:

• django-test-migrations

Статьи на тему:

• Vinta: Django zero-downtime migrations guide

Предыдущие части серии:

• Часть 1: Готовимся к миграциям и избегаем конфликтов

• Часть 2: Полезные советы и обход типичных подводных камней