- PVSM.RU - https://www.pvsm.ru -

Мой линтер миграций Django выдал 407 критичных тревог на шести больших проектах. 405 оказались ложными

Я делаю orm-lens [1], статический анализатор моделей и миграций Django. Одна из его проверок, migration-risk, читает каждый файл миграции и ищет операции, которые сломаются на таблице с данными: NOT NULL-колонку без значения по умолчанию, UNIQUE-колонку, которую нарушат уже существующие дубли, создание индекса с блокировкой таблицы.

Тесты были зелёные, и я запустил проверку на настоящих проектах:

Проект

Звёзд на GitHub

Критичных находок

NetBox

21.8k

212

PostHog

40.5k

79

authentik

26.2k

58

Healthchecks

10.5k

27

Plane

61.7k

25

paperless-ngx

47.4k

6

Итого 407 критичных находок. Я прочитал каждую. Настоящих оказалось две.

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

1. Squash-миграции никогда не выполняются на заполненной таблице (208 тревог)

class Migration(migrations.Migration):
    replaces = [("dcim", "0002_auto_..."), ..., ("dcim", "0059_...")]

Squash-миграцию Django выполняет только на пустой базе. В MigrationLoader.build [2]_graph() есть два сценария:

  • все заменённые миграции уже применены: squash помечается применённым и не выполняется;

  • применена только часть: squash удаляется из графа, и дальше идут оригинальные миграции.

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

Вывод для своих проверок: миграцию с replaces = [...] нельзя проверять как обычную. Она описывает схему с нуля.

2. Текстовые поля с blank=True получают "" (83)

migrations.AddField("virtualmachine", "serial",
                    models.CharField(blank=True, max_length=50))

Здесь нет ни default=, ни null=True, то есть колонка NOT NULL. На вид это классическая ошибка, но на деле всё безопасно. Посмотрите на BaseDatabaseSchemaEditor._effective_default(): если у поля нет default, оно не null, но blank=True и класс поля допускает пустые строки (empty_strings_allowed), Django подставляет "". Существующие строки получат пустую строку.

Проекты часто наследуются от CharField. У NetBox есть ColorField(blank=True, max_length=6), и для него работает то же правило. Поэтому линтер теперь считает признаком текстового поля аргумент max_length, а не имя класса.

3. Many-to-many не добавляет колонку (37)

ManyToManyField, TaggableManager из django-taggit и GenericRelation создают отдельную таблицу связей или не создают ничего. Риска NOT NULL для таблицы самой модели у них нет. Это очевидно, когда пишешь об этом словами, но в коде проверки AddField таких полей ничем не отличался от остальных.

4. makemigrations выносит внешние ключи из CreateModel (25)

migrations.CreateModel(name="ContactGroupMembership", fields=[...]),
...
migrations.AddField("contactgroupmembership", "group",
                    models.ForeignKey(..., on_delete=models.CASCADE)),

Чтобы разорвать циклические зависимости между моделями, автодетектор сначала создаёт таблицу без части FK, а потом добавляет их отдельными AddField в той же миграции. Таблица появилась несколькими строками выше, значит, она пустая, и NOT NULL без default тут ничему не мешает.

Вывод: состояние «таблица пустая» нужно отслеживать внутри списка operations, а не только на уровне файлов.

5. Squash и заменённые им миграции не образуют две ветки (17)

Django не применяет миграции приложения, если в графе два «листа» (это та самая ошибка Conflicting migrations detected). Моя проверка считала конфликтом приложения authentik: и squash, и последняя заменённая им миграция выглядели как листья.

Загрузчик Django сначала убирает заменённые узлы и перенаправляет их зависимости на squash, и только потом граф проверяется. Линтер теперь делает то же самое до подсчёта листьев.

6. auto_now, db_default и GeneratedField заполняются сами (16)

  • auto_now_add=True и auto_now=True: тот же _effective_default() подставляет текущее время при ADD COLUMN.

  • db_default (Django 5.0+): значение по умолчанию на стороне базы.

  • GeneratedField: значение вычисляет сама база.

Ни одному из них не нужен default=.

7. NULL не конфликтует с NULL (12)

models.CharField(blank=True, max_length=128, null=True, unique=True)

Существующие строки получат NULL. В PostgreSQL (по умолчанию, без NULLS NOT DISTINCT из 15-й версии), MySQL и SQLite уникальное ограничение не считает два NULL равными. Значит, добавлять такую колонку безопасно. То же касается default=None: authentik использует его на четырёх полях в трёх миграциях.

8. Имена, которые возвращаются (5)

RemoveField, а следом AddField с тем же именем или RenameField на него, оставляют поле на месте. То же с DeleteModel и последующим CreateModel. Линтер сравнивал каждое историческое удаление с текущим models.py, видел, что поле есть, и сообщал о расхождении. Историю надо проигрывать целиком, а не сравнивать отдельные операции с итоговой схемой.

9. Миграции данных, которые выполняются раньше (2)

В authentik NOT NULL-колонка добавляется сразу после RunPython, который, судя по комментарию, удаляет все строки таблицы. Статически доказать, что делает RunPython, нельзя. Поэтому такой случай теперь не «критично», а предупреждение с объяснением: «перед операцией есть RunPython, проверить не могу».

Две настоящие

В PostHog миграция 0308_add_indirect_person_override_constraints удаляет два FK и добавляет их обратно как NOT NULL без значения по умолчанию:

migrations.RemoveField(model_name="personoverride", name="old_person_id"),
migrations.AddField(model_name="personoverride", name="old_person_id",
                    field=models.ForeignKey(on_delete=..., to=...)),

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

То же упражнение для N+1

Вторая проверка, nplusone, ищет классический N+1: цикл по queryset, в котором на каждой итерации читается связанный объект, а select_related/prefetch_related на исходном queryset нет. Всё по AST, без запуска Django.

Шум был и здесь:

  • запись через связь (interface.vdcs.set(...)) считалась чтением;

  • одно поле предлагалось и в select_related, и в prefetch_related;

  • срабатывали циклы в тестах.

После исправлений я ради этой статьи заново прогнал проверку на свежих клонах saleor, wagtail и label-studio:

Проект

Файлов .py

Время

Находок

Из них high

saleor

4385

2,5 с

34

6

wagtail

1339

1,6 с

11

2

label-studio

770

1,1 с

5

5

Пример из saleor (saleor/attribute/utils.py), который проверка помечает с высокой уверенностью:

assigned_attrs_values = AssignedVariantAttributeValue.objects.filter(
    assignment_id__in=(a.pk for a in assignments),
    value_id__in=(...),
)
for value in assigned_attrs_values:
    ...
    value.variant_id = value.assignment.variant_id   # запрос на каждой итерации

value.assignment — это ForeignKey, и без select_related("assignment") на каждую строку уходит отдельный SELECT. Проверка так и подсказывает исправление: .select_related("assignment").

Ложные срабатывания тоже остались, и скрывать их нет смысла. В том же saleor проверка приняла line._prefetched_objects_cache за связь, а поле amount_authorized (это деньги, а не FK) — за внешний ключ. Оба случая с уровнем medium, то есть «по форме похоже на связь, но схема этого не подтверждает». Для CI поэтому стоит оставлять --confidence high.

Что я из этого вынес

Синтетические тесты проверяют, что правило делает то, что я написал. Правда ли написанное про Django, они не проверяют. Это могут показать только большие чужие кодовые базы. Теперь каждый PR перед мержем я прогоняю на корпусе реальных проектов (saleor, wagtail, label-studio) и сравниваю вывод до и после. Так уже поймал три регрессии, которые тесты PR пропустили. Каждая из девяти причин выше стала отдельным тест-кейсом, и рефакторинг, который «забудет», как Django мигрирует заполненную таблицу, уронит тесты вместо того, чтобы уехать в релиз.

Уровень находки должен соответствовать уверенности. Если линтер не может доказать риск, например потому что перед операцией стоит непрозрачный RunPython, он должен сказать «предупреждение, и вот почему я не уверен», а не «критично». Проверку, которая ошибается 405 раз из 407, перестают читать. Вместе с шумом пролистывают и две настоящие находки.

Попробовать на своём проекте

uvx orm-lens migration-risk      # рискованные миграции, по умолчанию только critical
uvx orm-lens nplusone            # N+1 и что добавить в select_related / prefetch_related

Инструмент читает только исходники: базы, settings-модуля и django.setup() не нужно, работает даже со сломанным venv. Лицензия MIT, без платных тарифов. Есть ещё расширение для VS Code (ER-диаграмма, автодополнение полей в .filter()) и MCP-сервер для AI-агентов, но это тема для отдельной статьи.

Если проверка ошибается на вашем проекте, заведите issue [3]. Весь этот список появился именно так.

А какие миграции ломали прод у вас? Особенно интересны случаи, которые статикой не поймать.

Автор: FROWNINGdev

Источник [4]


Сайт-источник PVSM.RU: https://www.pvsm.ru

Путь до страницы источника: https://www.pvsm.ru/postgresql/462639

Ссылки в тексте:

[1] orm-lens: https://github.com/FROWNINGdev/orm-lens

[2] MigrationLoader.build: http://MigrationLoader.build

[3] заведите issue: https://github.com/FROWNINGdev/orm-lens/issues

[4] Источник: https://habr.com/ru/articles/1110288/?utm_source=habrahabr&utm_medium=rss&utm_campaign=1110288