- PVSM.RU - https://www.pvsm.ru -
Я делаю 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 делает с базой, большая часть списка пригодится и без моего инструмента.
class Migration(migrations.Migration):
replaces = [("dcim", "0002_auto_..."), ..., ("dcim", "0059_...")]
Squash-миграцию Django выполняет только на пустой базе. В MigrationLoader.build [2]_graph() есть два сценария:
все заменённые миграции уже применены: squash помечается применённым и не выполняется;
применена только часть: squash удаляется из графа, и дальше идут оригинальные миграции.
В обоих случаях каждый AddField внутри squash попадает в пустую таблицу. На squash-миграции пришлось больше половины всех тревог, в одном NetBox их было почти двести.
Вывод для своих проверок: миграцию с replaces = [...] нельзя проверять как обычную. Она описывает схему с нуля.
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, а не имя класса.
ManyToManyField, TaggableManager из django-taggit и GenericRelation создают отдельную таблицу связей или не создают ничего. Риска NOT NULL для таблицы самой модели у них нет. Это очевидно, когда пишешь об этом словами, но в коде проверки AddField таких полей ничем не отличался от остальных.
migrations.CreateModel(name="ContactGroupMembership", fields=[...]),
...
migrations.AddField("contactgroupmembership", "group",
models.ForeignKey(..., on_delete=models.CASCADE)),
Чтобы разорвать циклические зависимости между моделями, автодетектор сначала создаёт таблицу без части FK, а потом добавляет их отдельными AddField в той же миграции. Таблица появилась несколькими строками выше, значит, она пустая, и NOT NULL без default тут ничему не мешает.
Вывод: состояние «таблица пустая» нужно отслеживать внутри списка operations, а не только на уровне файлов.
Django не применяет миграции приложения, если в графе два «листа» (это та самая ошибка Conflicting migrations detected). Моя проверка считала конфликтом приложения authentik: и squash, и последняя заменённая им миграция выглядели как листья.
Загрузчик Django сначала убирает заменённые узлы и перенаправляет их зависимости на squash, и только потом граф проверяется. Линтер теперь делает то же самое до подсчёта листьев.
auto_now_add=True и auto_now=True: тот же _effective_default() подставляет текущее время при ADD COLUMN.
db_default (Django 5.0+): значение по умолчанию на стороне базы.
GeneratedField: значение вычисляет сама база.
Ни одному из них не нужен default=.
models.CharField(blank=True, max_length=128, null=True, unique=True)
Существующие строки получат NULL. В PostgreSQL (по умолчанию, без NULLS NOT DISTINCT из 15-й версии), MySQL и SQLite уникальное ограничение не считает два NULL равными. Значит, добавлять такую колонку безопасно. То же касается default=None: authentik использует его на четырёх полях в трёх миграциях.
RemoveField, а следом AddField с тем же именем или RenameField на него, оставляют поле на месте. То же с DeleteModel и последующим CreateModel. Линтер сравнивал каждое историческое удаление с текущим models.py, видел, что поле есть, и сообщал о расхождении. Историю надо проигрывать целиком, а не сравнивать отдельные операции с итоговой схемой.
В 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 такая миграция упадёт. Вполне возможно, что на момент релиза таблица была пустой. Линтер этого знать не может и не делает вид, что знает.
Вторая проверка, nplusone, ищет классический N+1: цикл по queryset, в котором на каждой итерации читается связанный объект, а select_related/prefetch_related на исходном queryset нет. Всё по AST, без запуска Django.
Шум был и здесь:
запись через связь (interface.vdcs.set(...)) считалась чтением;
одно поле предлагалось и в select_related, и в prefetch_related;
срабатывали циклы в тестах.
После исправлений я ради этой статьи заново прогнал проверку на свежих клонах saleor, wagtail и label-studio:
|
Проект |
Файлов |
Время |
Находок |
Из них 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
Нажмите здесь для печати.